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.

| improve this answer | |

Your Answer

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