We're a place where coders share, stay up-to-date and grow their careers.
Great tips! I can attest to all of these.
I strongly agree with your statement about not following DRY blindly. I'd extend that out to any methodology or practice.
Additionally, I use commenting showing intent to leave my specification and intent inline in the actual code. The result is that, no matter how long I'm away from the code, I can always pick back up my thought processes where I left off; meanwhile, anyone else reading my code can pick up not just what I'm doing (which should be self-evident from the code itself), but why I'm doing it.
Loved CSI! Thanks for sharing.
I can't agree with you more! About two year ago I had to re-write an implementation of am algorithm I wrote 7 years earlier. Lucky me, I originally commented everything that the customer needed right next to the specific part of the code that did it. Saved me days. Literally days of work.
I didn't know about CSI. Thank you so much for a pointer to the article. #TIL
Being able to re-create the program in any other language using just the comments is a great north-star to have; obviously really hard to follow (especially in the beginning)
Glad you find it helpful! I should have also included the link to my article about how it works in practice.
I came with an open mind but after reading the CSI guide, it looks to me like a very stupid idea.
A clean, well written code should reveal intent from the code itself, from the variable and method names, and its structure; and the test, the function interface, and pre/postcondition/assertions should reveal the detailed specification and contracts, in which case nearly all CSI comments as exemplified in that guide will be redundant.
Reading clean code should feel like reading CSI. The CSI comments then becomes redundant.
If you write your code, tests, and assertions with the same care that you write CSI, then you will get an executable and self-checking CSI without the comments; and your reader won't have to read twice and they will never be misled by outdated or quickly phrased comments.
The CSI guide you linked encouraged commenting the intent on each line, IMO this is very ridiculous. If you write intent revealing code, the intent should almost always be fairly straightforward to read from the line itself. If it's hard to read an intent from the line, then it may be ok to add comment as a crutch, but much better would be to rewrite the lines so the intent of that line and how that line relates to other lines becomes clear from the code itself.
The hard part of reading code, and where intent revealing comments can definitely help, is deriving intent from a large piece of code. On the contrary, the CSI guide you linked discouraged such commentaries. A few strategically placed comments can help summarise the grand intent that's not immediately obvious from reading individual lines. Intent revealing comments should be reserved for these grand schemes, not for individual lines. Individual lines should be clear enough without comments, and line comments are used sparingly when the line cannot be made clearer otherwise.
That "stupid idea" has saved my company countless hours. Others have reported the same. If the proof is in the pudding, it must not be so stupid.
Not every practice is right for everyone, and CSI might not work for you, but based on your comments, I can safely say you either skimmed or grossly misunderstood the standard. I'm as much of an advocate for self-commenting code and proper tests as is humanly possible, but in practice, they don't make up the difference in the specific (common) situations where CSI fits in.
If anyone is interested in understanding how this actually works, I did write this article up. It addresses all of the aforementioned misunderstandings.
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:
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
We're a place where coders share, stay up-to-date and grow their careers.