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);
  }
}

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);
  }
}

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);
  }
}

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.