When doing something fancy, adding an explanatory comment is defintely a good thing (though I would generally advice against doing anything 'fancy'). For those specific cases, it all comes down to what is sufficiently idiomatic, and to only comment on the cases that aren't.
As a litmus test, I would suggest asking yourself the following question: would a developer that has 6 months of decent working experience with the language/framework/library/paradigm be expected to know about this approach or at the very least know how to easily look it up? That means that things like standards variable declarations, loops, typical pointer usage, filter vs reduce vs map vs flatMap all count as idiomatic.
There are some grey zones, such as default value variable declarations in JavaScript:
const foo = bar || "my default value";
For those, you could rely on an extension of the above principle: if these constructs are project/team conventions, they count as idiomatic within the project/team (i.e. if you've been working on the project/team for 6 months, there is no doubt that you know about and understand the construct).
As an example of something that definitely does not require comments, and where the comments do more harm than good:
// declare the counter and set it to the starting value
let count = 0;
// perform the loop
for (
// declare the loop variable and set it to the starting value
i = 0;
// every loop, check whether we've exceeded the maximum value to loop over
i < 20;
// increment the loop variable by 1
i++) {
// increment the counter with the loop variable
count += i;
}
I trust you see that this kind of commenting would belong perfectly in a textbook for beginner JavaScript, but is utterly pointless in actual production code. Now imagine that you have code like this, but 10 times as long, and somewhere in the middle you have
// framework X has an internal bug in code segment Y (see <link>), which we have to correct for here, otherwise our code segment Z blows up
const correctionFactor = foo * 1.05;
Because of all the pointless comments, that comment will hardly be noticable, while if you remove all the pointless comments any reasonable IDE or syntax-highlighting editor will make it stand out.
As a final comment (pun very much intended), I'd like to add that this isn't a black or white thing: adding a poor comment doesn't damn you, it just makes the code slightly less maintainable. But given how much code most developers work with, the little things add up quite fast, so it pays to keep them in check.
Thanks for the examples, you're right that these type of comments makes the code noisy (perhaps I'd still be OK having them if they get reworded and moved somewhere where they're not as disruptive as in your examples).
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
When doing something fancy, adding an explanatory comment is defintely a good thing (though I would generally advice against doing anything 'fancy'). For those specific cases, it all comes down to what is sufficiently idiomatic, and to only comment on the cases that aren't.
As a litmus test, I would suggest asking yourself the following question: would a developer that has 6 months of decent working experience with the language/framework/library/paradigm be expected to know about this approach or at the very least know how to easily look it up? That means that things like standards variable declarations, loops, typical pointer usage, filter vs reduce vs map vs flatMap all count as idiomatic.
There are some grey zones, such as default value variable declarations in JavaScript:
For those, you could rely on an extension of the above principle: if these constructs are project/team conventions, they count as idiomatic within the project/team (i.e. if you've been working on the project/team for 6 months, there is no doubt that you know about and understand the construct).
As an example of something that definitely does not require comments, and where the comments do more harm than good:
I trust you see that this kind of commenting would belong perfectly in a textbook for beginner JavaScript, but is utterly pointless in actual production code. Now imagine that you have code like this, but 10 times as long, and somewhere in the middle you have
Because of all the pointless comments, that comment will hardly be noticable, while if you remove all the pointless comments any reasonable IDE or syntax-highlighting editor will make it stand out.
As a final comment (pun very much intended), I'd like to add that this isn't a black or white thing: adding a poor comment doesn't damn you, it just makes the code slightly less maintainable. But given how much code most developers work with, the little things add up quite fast, so it pays to keep them in check.
Thanks for the examples, you're right that these type of comments makes the code noisy (perhaps I'd still be OK having them if they get reworded and moved somewhere where they're not as disruptive as in your examples).