DEV Community

Muhammad Muhktar Musa
Muhammad Muhktar Musa

Posted on

Javascript and code documentation

javaScript is a programming language that conforms to the ECMAScript specification. JavaScript is high-level, often just-in-time compiled and multi-paradigm. It has dynamic typing, prototype-based object-orientation and first-class functions.

Why code documentation?

If you wrote a couple of functions for making an HTML table with JavaScript. You could use those function right now, or pass them to another developer. Everything is clear in your mind the moment you write the code, yet a month later you don't remember how to use function A or function B anymore. How function A is supposed to be called? What parameters it takes? And what shape should the parameters have?
Code documentation helps you and other developers understand how to use the software you wrote. There are many ways for documenting a piece of code. For example you can write:

  • howtos guides for using your code
  • a nice README for the repo
  • code documentation in the source But on top of how-to and READMEs, code documentation in the source holds most of the value. It sits right there with the code and helps avoiding mistakes as you write JavaScript in the editor.

Consider the following function:

function generateTableHead(table, data) {
  const thead = table.createTHead();
  const row = thead.insertRow();
  for (const i of data) {
    const th = document.createElement("th");
    const text = document.createTextNode(i);
    th.appendChild(text);
    row.appendChild(th);
  }
}
Enter fullscreen mode Exit fullscreen mode

This function kind of speaks for itself, generateTableHead. The data parameter doesn't specify what it should execute or what data should be.
If we look at the function's body, it becomes evident that "data" must be an array. table on the other hand does not make it clear if it is to be a string or an actual html element.
We simply as add a comment before the function:

/**
 * Generates a table head
 */
function generateTableHead(table, data) {
  const thead = table.createTHead();
  const row = thead.insertRow();
  for (const i of data) {
    const th = document.createElement("th");
    const text = document.createTextNode(i);
    th.appendChild(text);
    row.appendChild(th);
  }
}
Enter fullscreen mode Exit fullscreen mode

This is the standard code documentation. The function generateTableHead" should take an HTMLTableElement and an array as parameters. We can add annotations for both like

/**
 * Generates a table head
 * @param {HTMLTableElement} table - The target HTML table
 * @param {Array} data - The array of cell header names
 */
function generateTableHead(table, data) {
  const thead = table.createTHead();
  const row = thead.insertRow();
  for (const i of data) {
    const th = document.createElement("th");
    const text = document.createTextNode(i);
    th.appendChild(text);
    row.appendChild(th);
  }
}
Enter fullscreen mode Exit fullscreen mode

Code documentation is often overlooked and considered more or less a waste of time. Great code should speak for itself. And that's true to some extents. Code should be clear, understandable and plain. Writing documentation for code can help your future self and your colleagues.

Top comments (5)

Collapse
 
jacksuede profile image
JackSuede

I don't have any experience doing this, so I can't proclaim that it is worthless. But as far as clarification of the function goes, the description is basically just the function name with spaces, the table parameter is pretty obvious too. The real fix here then is to give a much more descriptive name to the parameter "data", which is the whole reason for the documentation. Maybe this was just a bad example for proving your point, but this function only needs to be a little more descriptive.

Collapse
 
mcube25 profile image
Muhammad Muhktar Musa

it is just for making the points sake, the example does not really matter

Collapse
 
devman9000 profile image
devman9000

or use TypeScript.

Collapse
 
iamchriswick profile image
Christian Wick

Still needs to be documented.

Collapse
 
djpavlovic profile image
djpavlovic

Writing good JSDoc can save hours and hours of debuging code, while simply @summary @description @param with JSDoc declaring input and output params can be. Also IDE can warn you about issues you may end up with ...
I suggest you to read docs about it: jsdoc.app/

example