Build & Development Commands
Testing Guidelines
- For each code generate stub with test data to test positive, negative, edge cases - Test for performance - Test for best practice
Code Style & Guidelines
- Follow consistent naming conventions:
camelCase
for variables and functions, PascalCase
for Script Includes. Use descriptive and meaningful names.
- Write clear, concise comments explaining the purpose ("why") of complex code sections, not just restating what the code does. Use JSDoc-style comments (
@param
, @returns
, @description
) for Script Includes and public functions. - Encapsulate reusable server-side logic within Script Includes. Avoid global Business Rules or global UI Scripts; call Script Includes instead. Ensure Script Includes are well-defined and testable. - Minimize direct DOM manipulation in Client Scripts. Prefer g_form
and g_user
APIs. Avoid unsupported libraries or direct jQuery usage where ServiceNow APIs suffice. - Avoid using GlideRecord
directly in Client Scripts due to performance impact. Use GlideAjax
to call Script Includes for server data retrieval or updates. Use g_form.getReference()
with callbacks sparingly and understand its performance implications. - Configure Business Rules to be specific and efficient: run Before/After/Async; target specific operations (Insert, Update, Delete, Query); use conditions to limit execution. Avoid Display Business Rules if possible due to performance overhead. - Optimize server-side queries (GlideRecord
, GlideAggregate
):
- Use specific
addQuery()
, addEncodedQuery()
conditions. Filter as much as possible in the query.
- Avoid querying inside loops. Fetch necessary data beforehand if possible.
- Use
setLimit(1)
when only expecting a single record.
- Retrieve only necessary fields (avoid
*
). Use get()
for single records when appropriate.
- Use
GlideAggregate
for record counts or aggregate calculations (SUM, AVG, MIN, MAX) instead of iterating through GlideRecord
.
- Implement robust error handling using
try...catch
blocks, especially for integrations, complex server-side logic, and potential failure points. Log errors meaningfully using gs.error()
, gs.warn()
. - Write small, focused functions/methods adhering to the Single Responsibility Principle. - Use var
, let
, and const
correctly to manage variable scope within scripts. Avoid creating unintended global variables. - Always check for valid records/objects before attempting to use them (e.g., if (gr.next()) { ... }
, if (user && user.exists()) { ... }
). - Adhere to ServiceNow API best practices and avoid using deprecated methods. Consult developer documentation regularly. - Prefer asynchronous operations (Async Business Rules, GlideAjax
, Flow Designer) for long-running tasks to avoid blocking user sessions.
Documentation Guidelines
- Provide clear and informative descriptions in the 'Description' field for all configuration records (Business Rules, Client Scripts, UI Actions, Script Includes, Tables, Fields, Roles, ACLs, Flows, etc.). Explain the purpose and function. - Use descriptive names and detailed 'Description' fields for Update Sets and Application versions, outlining the changes included and their purpose. - Utilize JSDoc-style comments (
@param
, @returns
, @description
) within Script Includes to document methods, their parameters, return values, and overall purpose, facilitating understanding and reuse. - Comment complex or non-obvious logic within scripts, explaining algorithms, workarounds, or critical business decisions implemented in the code. - Document integration details thoroughly, including endpoint URLs (use System Properties), authentication methods, data mappings, expected request/response formats, and error handling strategies. Store this in relevant records (e.g., REST Message) or supporting documentation (e.g., Knowledge Base). - Maintain a Technical Design Document (TDD) or similar documentation for significant custom applications or features, covering architecture, data model, key components, security design, and operational considerations. - Ensure Scoped Application records (sys_app
) have accurate metadata, including descriptions, scopes, version numbers, and dependencies. - Clearly document the purpose and usage of System Properties (sys_properties
) used by custom code or configurations.