2 ms·
At my work we have basically banned "what" comments for blocks of code. JSDoc comments can still document what a function does at a high level but it should not
by EliasWatson 1mo ago
At my work we have basically banned "what" comments for blocks of code. JSDoc comments can still document what a function does at a high level but it should not go into implementation details unless they are important to anyone using the function. And any comments inside the function should always be for explaining why, not what. The "what" of a piece of code should be self explanatory by just reading the code. If it's not, then you likely should rewrite it to be more clear (sometimes hard-to-read code is necessary and then a "what" comment would be appropriate, but this is rare).
"What" comments almost always end up falling out of date or even sometimes being slightly incorrect from day one. Incorrect comments lead to confusion and bugs. If a comment says some code does X but the code actually does Y, then you don't know whether the comment is just out of date or if Y is actually a bug. But if a comment explains the intention of the code and the code contradicts that intention, then you know it's likely a bug.