I have to edit other people's JavaScript code. The code usually loads some data from a Web API, generates a table, places it into the HTML page, and attaches some event handlers.

Due to the async nature, the program flow is pretty confusing, so I am trying to briefly document it, otherwise each time I get lost trying to figure out which part of the code I need to modify. For example, if I need to modify some values after the data is loaded from a Web API, but before it is put into the table, I need to figure out where the data load happens and where the HTML rendering happens.

Here is the way I am doing it:

 * @fileOverview Custom code for the Candidates List page.
 * Program flow on page load:
 * - customSearchInit()
 *   - initSearchPage()
 *     - populateDropdownFields()
 *     - LoadAdditionalListDataAndContinue()
 *       - loadListData()
 *         - generateHtmlTable()
 *         - finishAsync()
 *           - completePageLoad()

Is there a recommended / popular syntax for documenting the program flow? Is this a common practice to do it?


The common way to illustrate behavior in a human-consumable way is with a sequence diagram. It shows the collaboration between system components, and can handle complexities like concurrency and asynchronous messages.

I think your in-code syntax is going to be difficult for anybody but you to understand, and instead I would create a sequence diagram that lives in the project's documentation, and you can use a JSDoc (I assume from the @fileOverview tag that you're using JSDoc) link to reference the sequence diagram.

 * @fileOverview Custom code for the Candidates List page.
 * See [this diagram](../docs/candidates-sequence.png) to understand the behavior of the page load

I prefer to use the text-based sequence diagram description tool PlantUML to create my sequence diagrams. It's open source and since it's text-based it makes it easy to version-control. If you really wanted to, you could even put the PlantUML code right into your file documentation by wrapping with <pre><code> tags.

Beware that documentation like this often deviates from the actual implementation as the implementation changes.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.