|We had lots of discussion about this at work too, about how extensively code should be commented, and if at all.
First there is a difference between commenting and documenting code. The latter you probably need to do anyway, at least for public APIs. Besides that, imho some visual indicator on top of each function / class etc makes it easier to navigate through code. So a short block on top of each function can act as kind of a separator (like headlines in normal texts), that allows to quickly see where a function starts. So (meanwhile) I add at least a single line with dashes on top of each function, and find that quite useful.
As for comments, I agree with those people, who say code should be written in a way that comments are not necessary. Means: Use names that say what it is about rather than comments, split complicated constructs into multiple steps, even if it appears less "cool" (functional programming!) etc.
However, there are cases, where comments are a good idea. Not just to explain some parts of the code that are hard to understand, but also to indicate that something might look like a bug or a wired construct, but is actually intended. Like this JS:
const a = parseInt(someString, 10);
if (!(a > 0))...
One might think "Wtf? Why not
if (a <= 0)...?", and forget, that the former also takes care of
So my personal guideline:
- Write code that doesn't need comments.
- Comment to avoid misunderstandings.
- Document your code.