Comment by Denny Trebbin on "What tools do you use to document your ES6/JavaScript code?"

CommentWhat tools do you use to document your ES6/JavaScript code?

Denny Trebbin

Lead Fullstack Developer. Experimenting with bleeding-edge tech. Irregularly DJ. Hobby drone pilot. Amateur photographer.

Jun 20, 2016

Hi,

We don't use code documentation tools anymore since ES6. The issue was/is that none of the existing documentation tools used Babel to parse the code. The result was strange. Babel generated working code while esdoc for example failed and didn't produce anything - we never checked it again. Our workaround was to do code reviews instead. Now we talk about the code and refactor it together. We also have no de-sync issues (between code and generated documentation) anymore. And our workaround became the standard.

Tom Fagerland

Trying to learn webdev

Jun 22, 2016

Independent of everything else, do you find that code review takes more or less time than documenting?

It's hard to say. While establishing such culture, it takes more time (in the beginning) than just writing bad comments.

/**
 @param {object} db database query object.
 @return  {void} no return value
*/
const runDbQuery(db) {
  /* create object */
  let json = JSON.parse(db.query.result)
  if (!json) throw new Error('Error, Parsing JSON failed') // invalid JSON
  doSomething(json)
}

The snippet from above we found last year .... Neither of the comments is useful. The condition is useless because unless JSON.parse() throws, it will always create an object. Surround JSON.parse() with a try-catch block would be the correct thing to do. Documenting obvious facts is as useless as the included error message.

Establishing code-reviews enables the entire team to learn from each other. Eliminate code-smell, fix logical errors, reduces the time to understand other's code. It's not the holy grail but it's better than betting on documentations.

Search Hashnode