I agree that expressive code generally fails at the "why". Seeing your comment about "comments that are just repeating what the code itself said", I'm curious if you would consider commenting code that takes an extra mental effort understanding what they do, for example:
I'm sure every language have something that, although they have a way to do it, it is not as expressive as in other languages. I generally tend to document when I'm using some wizardy code that can't be made expressive (e.g bit operators) and I don't expect the reader to be a master at the language that it's being used (I don't expect everybody to know bit operators). I write code for Junior Devs since I'm a Junior myself :) .
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).
I write code for Junior Devs since I'm a Junior myself :)
This is one of the reasons I love having access to less-experienced folks at work. When I find myself looking at some code I've written and questioning its clarity, I have often pinged it over to a junior or someone with a different context than I have and asked:
If you stumbled onto this logic in a file that does X, without further context - what would you expect it to do?
If I can make that clear to a second set of eyes without a plethora of comments, I consider that a big win and another step toward writing cleaner, easier-to-grok code.
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.
Hey Alain,
I agree that expressive code generally fails at the "why". Seeing your comment about "comments that are just repeating what the code itself said", I'm curious if you would consider commenting code that takes an extra mental effort understanding what they do, for example:
[1, 2, 0, false, "foo", null, undefined].filter(Boolean)or
return value | 0I'm sure every language have something that, although they have a way to do it, it is not as expressive as in other languages. I generally tend to document when I'm using some wizardy code that can't be made expressive (e.g bit operators) and I don't expect the reader to be a master at the language that it's being used (I don't expect everybody to know bit operators). I write code for Junior Devs since I'm a Junior myself :) .
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).
This is one of the reasons I love having access to less-experienced folks at work. When I find myself looking at some code I've written and questioning its clarity, I have often pinged it over to a junior or someone with a different context than I have and asked:
If I can make that clear to a second set of eyes without a plethora of comments, I consider that a big win and another step toward writing cleaner, easier-to-grok code.