How I use JSDoc for SuiteScript

Created: May 9, 2024

Sustainable SuiteScript reader Matt Poloni wrote in with the following question:

Do you use JSDoc above and beyond the minimum required to deploy scripts? If so, are there any particular patterns that you find useful when using it?

I absolutely use JSDoc well beyond the minimum required for deployment. I document my NetSuite systems using all sorts of tools, including JSDoc.

As important as what I do document is what I don't document. Not all documentation is created equal, and good documentation requires a significant investment of time and energy throughout the entire lifecycle of the project. I want to make sure I make the most of that investment.

Every good system adapts and evolves over time, and good documentation must adapt and evolve right alongside the system.

Creating good documentation - and thus being a good documentor - is a habit that is cultivated over time, not a task that is checked off a list.

What I don't document

Flowcharts, comments, or any similar docs/diagrams which describe exactly what any particular code does. The code itself is the only reliable source of truth of how the code works. Documenting this separately bifurcates the source of truth and immediately creates an unreliable document; unreliable documentation is worse than no documentation.
Comments that re-state what a line of code does. Comments are not the place to teach code literacy. If a line of code is so cryptic that it needs a comment to explain it, I re-write the line(s) for clarity rather than relying on a comment that I'll forget to update.
```
// I *avoid* comments like this:

// Load the Sales Order record
record.load({ type: record.Type.SALES_ORDER, id: orderId })
```

What I document

Flowcharts or similar docs/diagrams of the business processes and use cases involved in the system.
Component diagrams of the major architectural pieces of the system and their relationships to each other.
Explanations of why a piece of code exists. The Why of a piece of code is a little more timeless than the What, and it is something you cannot get from reading the code. I try to document the reasons behind my architectural and functional decisions, particularly where some sort of compromise or shortcut or similar non-obvious tradeoff is made.
Type definitions for the programmatic data structures in the system using the @typedef directive. This way, my IDE can provide code completion and warn me when I reference properties incorrectly. I typically place these type definitions in a typedef.js file at the root of the SDF project.
The programmatic contract (i.e. the inputs and outputs) of my functions using directives like @param, @returns, and @throws.
Governance usage of functions using the @gov directive from jsdoc-plugin-suitescript.
Module-level documentation containing the purpose of the module, a programmatic name of the module for code completion using @module, the licensing of the code using @license, and more.

Take a look at this repository to see several realistic examples of how I document my SuiteScript.

Where I put documentation

Knowledge is contextual. If no one can find my documentation in the contexts when and where they need it, then I shouldn't have bothered to write it in the first place.

I always want my documentation as close as possible to the point where it is relevant. That means if I'm documenting a code system, I want the documentation as close to that code as possible.

The comments for a piece of code exist directly on that piece of code. The further away the documentation is from the code it documents, the less discoverable the documentation is, and the less likely it is to stay updated.
Links to relevant external documentation are added in code comments with the @see directive. This is helpful for linking to things like requirements documentation, relevant issue trackers or tickets, architecture diagrams, or the Stack Overflow question I borrowed code from (I see you).
A README document acts as the hub of knowledge for the system, explaining relevant context for the system and routing the reader to important external documentation. The README is deployed right alongside the code it documents and lives in the File Cabinet with them. If I'm building an integration with SFDC, and the source files for the project get deployed to File Cabinet/SuiteScripts/sfdc-integration, then File Cabinet/SuiteScripts/sfdc-integration/README will be the documentation hub for that project.

HTH

-EG