In ServiceNow development, proper documentation is crucial for maintaining code quality and ensuring that functions are easily understandable by other developers. For me, I prefer using JSDoc standards for documenting my code, so let me give you a brief rundown in case you’ve never heard of it.
This blog post is split into two parts: explaining my JSDoc process, and then a full + real example of me performing this process on a script include I wrote.
Importance of JSDoc
JSDoc is basically a markup language used to annotate JavaScript source code files, making it easier to understand the purpose and functionality of various functions and methods. By adhering to JSDoc standards, ServiceNow developers can create solid documentation that serves as a reference for both current and future team members. This practice not only improves code readability but also facilitates smoother onboarding for new developers.
Plus, with a little help of generative AI I can generate JSDoc comments quickly, and then with my newly documented code, I can generate separate, stand-alone documentation quickly so that my teammates never have to jump into the script include in the first place.
My Script Include + JSDoc process
-
Write my Script Include as normal
-
Have an LLM generate the JSDoc markup
-
Correct any mistakes
-
Have an LLM generate stand-alone documentation
Basic JSDoc Syntax
To effectively document your ServiceNow scripts or understand the syntax when you encounter it, familiarize yourself with the basic syntax of JSDoc. Here are the basics:
Function Documentation
When documenting a function, you should include the following tags:
-
@function: Indicates the name of the function. -
@Param: Describes the parameters the function accepts. -
@returns: Specifies the return value of the function.
Example:
/**
* Calculates the total price of items in the cart.
* @function calculateTotal
* @param {Array} items - An array of item objects.
* @returns {number} The total price of all items.
*/
function calculateTotal(items) {
let total = 0;
items.forEach(item => {
total += item.price;
});
return total;
}
Documenting Variables and Objects
You can also document variables and objects using JSDoc:
/**
* Represents a shopping cart item.
* @typedef {Object} CartItem
* @property {string} name - The name of the item.
* @property {number} price - The price of the item.
*/
/**
* An array of items in the shopping cart.
* @type {Array<CartItem>}
*/
const cartItems = [];
Best Practices for JSDoc in ServiceNow
-
Be Consistent: Use the same format and structure throughout your documentation to maintain clarity.
-
Keep it Updated: Regularly update your JSDoc comments as your code evolves to ensure accuracy.
-
Use Descriptive Names: Choose meaningful names for functions and parameters to make the documentation self-explanatory.
-
Include Examples: Where applicable, provide examples of how to use functions to enhance understanding.
A full example of me doing this last night
I wrote this blog post up because just last night I finished building an integration between a ServiceNow instance and the ServiceNow Community platform.
1. Wrote my code as normal
I created a new Script Include in my PDI and set up several functions: some that I meant to be “public facing” (as in, my teammates would use them) and some were helper functions that would be called by other functions (never by other scripts).
2. Generated JSDoc Markup
I use both Cursor and ChatGPT 4o to do this step, especially because I built this on a PDI, but if you have access to Now Assist for Code, then that would work too.
My prompt:
Generate JSDoc comments for these public facing functions: [list]
Yeah, it’s a simple prompt, but JSDoc is so well documented and generative AI is smart enough to be able to understand your functions pretty well.
/**
* Gets message information from the Khoros API for one or more message IDs
* @param {string|string[]} messageId - Single message ID or array of message IDs to retrieve
* @returns {Object|Object[]} Message information object(s) from the API response
*/
Notice how it even hinted that the input parameters could be a string or an array of string, it knew that I had scripted in that flexibility
3. Correct Mistakes
It’s generative AI, always take a look at what it produced for you and verify that it is correct. In this case, I didn’t find any mistakes actually.
4. Generate Stand-alone Documentation
Generally speaking, it’s good as-is if my goal was to provide easy to understand in-line documentation. Personally, I don’t want to force my teammates to visit the script include just to see what they need. So I take it a step further and generate stand-alone documentation. Again, generative AI makes this really easy.
First, some prep work.
Usually, when I test my scripts to see if they work, I call my script include from other locations like Background Scripts or Business Rules, etc. I make sure to save all those calls and add them as a comment block at the end of my script include:
Why do I do this? Well, it helps with the following prompt:
Create markup documentation for the following ServiceNow Script include. Create a description, parameter and return explanation, and example usage for each of the follow public facing functions: [list]
Then, create additional brief documentation for all other functions in the script include. These are internal helper functions, only to be described for posterity.
Then let the LLM do its magic! I take the generated documentation and throw it onto something like GitHub gists and now I can share it to my teammates for their future reference.
While you’re at it, this is where I tend to also provide sample returns. Especially if the return is a lengthy JSON object, then my teammates can create their code with my sample return object instead without having to run the call themselves first.
Happy documenting!
- Earl
3 Comments
