Describing JS program flow in @fileoverview

Question

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?

Answer 1

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.