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.
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) thrownewError('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.
Denny Trebbin
Lead Fullstack Developer. Experimenting with bleeding-edge tech. Irregularly DJ. Hobby drone pilot. Amateur photographer.
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.