I'm a web sysop and support engineer. My skills are mainly in back-end: Java, Linux, Python, PostgreSQL, Git, and GitLab. Currently I'm learning front-end skills: JavaScript, and Ruby.
But certainly, no "rule" should be followed religiously (that is, without question or thought). Which is a common thread among the OP's other rules, and my own Rule 0.
Calling it a "Stupid Idea" is a little harsh. But I do agree with the more positive sentiments expressed in Lieryan's post. The example I've attached from the CSI, in particular, seems to illustrate the point well. It's literally just repeating the code in English:
I'd argue that you should take Lieryan's suggestion as far as you can go, and then only when you still have ambiguity should you resort to CSI. Even then, you'd need to make sure that your comments are truly adding value and not just repeating what's already evident from the code (as with the attached example).
The only trouble with deciding whether a comment is "useful" or not while you code is that, during the process, everything you do seems obvious. The non-obvious intent only becomes apparent upon revisiting.
This is why CSI advocates commenting everything now, and then refactoring the comments once the code isn't as fresh in your mind. It's easier to drop a comment that isn't useful, than to try and figure out what intent-comment you SHOULD have included, but didn't.
None of that should be in lieu of any other component of clean coding, mind you. The code's "what" should still be self-evident, without comments. Comments are only for why, and I have never come across a single production-level code base where the intent was even sufficiently suggested by the self-commented code.
Usually, the people who say that intent-commenting is redundant to clean code are those who have never actually put intent-commenting into practice; it's dismissed because, as clean code likes to declare in its limited, but somehow magically all-seeing manner, "comments are always a failure."
I use both, and one can't even pretend to replace the other.
I just realized (and this isn't aimed at any particular person here), but I think that from a psychological perspective, one reason people seem to be so uncomfortable with the idea of commenting intent traces back to imposter syndrome...
There are those coders who write "clever" code that the average programmer is simply awestruck by. Even when it's completely "clean", the cerebral nature of the code is just too incomprehensible to any but the most senior developers...yet nothing particularly clever is actually being accomplished. The developer in question is trying to be Mel, and the moment they actually admit what the intent ("why") of their code is..."Oh, I'm just searching for a value in an array"...the smoke is cleared away, exposing their Cleverness as mere Overengineering.
I'm far from suggesting this is a common reason for opposing intent-commenting, but I have no doubt it is one of the reasons.
On a broader scale, however, I think it isn't unreasonable to assume that there are plenty of coders who naturally fear code critique by their peers, and if they're entirely up-front about their intent, they'll be subject to feedback along the lines of "Why are you doing this the hard way?"
By keeping our intent to ourselves, we feel like we can hide behind our (otherwise clean) code. Most of our peers won't bother to read it in light of what it's intended to be doing, so we're more likely to get "LGTM" code reviews and glaze-eyed pats on the back. Intent commenting exposes our inner thought processes to the open source world for public scrutiny, and I think that scares the Dickens out of a lot of people.
I'm a web sysop and support engineer. My skills are mainly in back-end: Java, Linux, Python, PostgreSQL, Git, and GitLab. Currently I'm learning front-end skills: JavaScript, and Ruby.
I'm a web sysop and support engineer. My skills are mainly in back-end: Java, Linux, Python, PostgreSQL, Git, and GitLab. Currently I'm learning front-end skills: JavaScript, and Ruby.
I feel my future self will disown any gratuitous 'cleverness', so for me personally, a comment on some clever code is more likely to be an admission to Future Self of being too much clever, and not enough smart :-)
Also, it's a little like explaining the punch line of a joke. One either feels that the joke has failed, or else being condescending to explain it. Another form of imposter syndrome
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.
mmm
I've been flip/flopping between comments are a last resort, okay and these specific kinds are actually good. And then there is literate programming which seems to be something along the lines of CSI, which I'd not heard of before.
But certainly, no "rule" should be followed religiously (that is, without question or thought). Which is a common thread among the OP's other rules, and my own Rule 0.
Calling it a "Stupid Idea" is a little harsh. But I do agree with the more positive sentiments expressed in Lieryan's post. The example I've attached from the CSI, in particular, seems to illustrate the point well. It's literally just repeating the code in English:
thepracticaldev.s3.amazonaws.com/i...
I'd argue that you should take Lieryan's suggestion as far as you can go, and then only when you still have ambiguity should you resort to CSI. Even then, you'd need to make sure that your comments are truly adding value and not just repeating what's already evident from the code (as with the attached example).
The only trouble with deciding whether a comment is "useful" or not while you code is that, during the process, everything you do seems obvious. The non-obvious intent only becomes apparent upon revisiting.
This is why CSI advocates commenting everything now, and then refactoring the comments once the code isn't as fresh in your mind. It's easier to drop a comment that isn't useful, than to try and figure out what intent-comment you SHOULD have included, but didn't.
None of that should be in lieu of any other component of clean coding, mind you. The code's "what" should still be self-evident, without comments. Comments are only for why, and I have never come across a single production-level code base where the intent was even sufficiently suggested by the self-commented code.
Usually, the people who say that intent-commenting is redundant to clean code are those who have never actually put intent-commenting into practice; it's dismissed because, as clean code likes to declare in its limited, but somehow magically all-seeing manner, "comments are always a failure."
I use both, and one can't even pretend to replace the other.
I just realized (and this isn't aimed at any particular person here), but I think that from a psychological perspective, one reason people seem to be so uncomfortable with the idea of commenting intent traces back to imposter syndrome...
There are those coders who write "clever" code that the average programmer is simply awestruck by. Even when it's completely "clean", the cerebral nature of the code is just too incomprehensible to any but the most senior developers...yet nothing particularly clever is actually being accomplished. The developer in question is trying to be Mel, and the moment they actually admit what the intent ("why") of their code is..."Oh, I'm just searching for a value in an array"...the smoke is cleared away, exposing their Cleverness as mere Overengineering.
I'm far from suggesting this is a common reason for opposing intent-commenting, but I have no doubt it is one of the reasons.
On a broader scale, however, I think it isn't unreasonable to assume that there are plenty of coders who naturally fear code critique by their peers, and if they're entirely up-front about their intent, they'll be subject to feedback along the lines of "Why are you doing this the hard way?"
By keeping our intent to ourselves, we feel like we can hide behind our (otherwise clean) code. Most of our peers won't bother to read it in light of what it's intended to be doing, so we're more likely to get "LGTM" code reviews and glaze-eyed pats on the back. Intent commenting exposes our inner thought processes to the open source world for public scrutiny, and I think that scares the Dickens out of a lot of people.
Yes. Emphasis on adding value. Repeating code in English (or another human language) is one of my pet peeves, but if it adds value, then I'm for that.
Precisely! Intent-comments only work if they add value: a clear expression of the intention apart from the code itself.
That's one of the major reasons I wrote the standard: to differentiate between junk comments and useful ones, and to encourage the latter.
+1 for mention of Mel
I feel my future self will disown any gratuitous 'cleverness', so for me personally, a comment on some clever code is more likely to be an admission to Future Self of being too much clever, and not enough smart :-)
Also, it's a little like explaining the punch line of a joke. One either feels that the joke has failed, or else being condescending to explain it. Another form of imposter syndrome