Annotate scripts and customizations with comments

[Dawn Jurek]

Have you ever coded a complex function or customization, only to look at it later and realize you forgot to annotate it with comments, or skipped this step to save time? In this first installment of our best practices series, we look at the importance of accurately commenting your scripts and customizations.

Why is commenting on your scripts and customizations so important?

The script or customization details may be obvious to you today but may not be clear to you or others who must use or update the item in the future. Providing helpful comments as part of the development and upgrade process is well worth the effort and can save you and others a lot of time and trouble later. Most code is read many more times than it is written. Give your future self (and colleagues) insight into your thoughts! Here's what we recommend.

Annotating scripts and customizations best practices:

When writing scripts or customizing records, follow these best practices to avoid confusion.

• Add clear and accurate comments that provide relevant information. Comments can include such as what the script or record does, its inputs and outputs, the business justification, and configuration requirements.
• For scripts, use the proper style and tags required to start and end comments in the specific scripting language. It's best practice to comment every substantial section of code, describing what the intent is behind it so that others looking at it later will understand how it works.
• For other records, add descriptions to help users and developers understand its content and functionality. Important records to describe include business rules, UI actions, and access control list (ACL) rules. Most ServiceNow records have at least one field for descriptions or comments, such as the Description field. This field is not always visible by default and may need to be added by configuring the form.
• Where applicable, include cross-references to related records or business requirements to provide additional information and context.
• When you update a script or record, also update the comments, as needed.

Behind the scenes here at ServiceNow, the Knowledge Management team works closely with subject matter experts to disseminate critical information to our customers. We've found that certain topics come up frequently, in the form of best practices that can help you keep your ServiceNow instances running smoothly. This series aims to target those topics so that you and your organization can benefit from our collective expertise.

To access all of the blog posts in this series, search for "nowsupport best practices series."