In an earlier post on the philosophy of code comments, I noted that the best kind of comments are the ones you don't need. Allow me to clarify that point. You should first strive to make your code as simple as possible to understand without relying on comments as a crutch. Only at the point where the code cannot be made easier to understand should you begin to add comments.
Thank you for your blogâi read it almost every day and find it informative and interesting.
Sometimes when iâm writing code, i think âi should commentâ thisâonly to realize that the comment is needed because itâs not clear how it works.
comments i gravitate to now are those that say âwhyâ or indicate the intent of the code.
I always ask myself, âWhat questions would be asked by someone looking at this code for the first time?â And then I write comments to answer those questions.
Sometimes when Iâm writing code, I think âI should comment thisâ
Right. The first and proper response to that feeling is to roll up your sleeves and refactor the code. After youâve refactored, if you still feel a comment is necessary, then by all means add one. Never comment before youâve attempted to refactor away the comment first.
You are absolutely right - comments should describe the thinking behind the code, not the code. Especially important are decisions that were tried and failed.
Your example of a good comment sucks. Itâs describing the code, not the thinking behind it. If you need context for the reverse string operation, why not write a âreverseâ method?
A better comment might be âReverse the string as a weak obfuscation techniqueâ (for example)
As always, excellent. Right to the point and informative.
In favor of comments vs. no-comments, with the advances in IDE, most offer syntax highlighting these days.
Sometimes, while reading a sequence of black and blue (standard VS colors), having a a line of green in the middle makes it jump out.
The reverse goes of course⌠too much green kills the green.
I agree with Robert. If I have to write comments like â# Reverse the stringâ its going to end up with more comments than code. If a developer considers that to be opaque theyâre better off not even trying âŚ
Dave, as pointed out in the early part of the article, comments should be useful not primarily for the person who writes them, but for those who read them.
While the example given may not be so obvious for most Perl programmers (experience level?), it may not be that obvious to non-Perl savvy programmers.
And it is possible that some may, one day, want to convert that particular program to a different platform or language. In that particular case, it is very likely that the person who reads the comments (the intended audience of comments after all), is mostly interested in the âwhat?â and not the âhow?â.
And from personal experience, my coding style does evolves, impacted by several factors, including platform evolution, language evolution, experience. If I look back, I may not write the same line(s) of code to do the same thing months or years later.
In general, the amount of comment needed for a line depends on its complexity.
int i = 0;
Does not need comments.
return new ObjectEl(Math.Max(arg1, arg2), RetrieveObect(arg3, DB_NAME))
probably would require a comment. Even better, as suggested in by Jeff and other poster, it could be re-written to be self explanatory.
Writing compact lines of code does not produce compact code or faster code⌠leave it up to the compiler. But I guess thatâs a whole different article (Jeff
ugh. since when did writing code become intertwined in the eccentric world of art. Suggestion. If youâve hired programmers that are too stupid to read either the comments or the code, youâre SOL. If I hired someone that wasted their valuable brain power on this nonesense weâd never get anything done, and Iâd most likely fire the guy on the spot. Leave this eclectic crap to abstract spatter paintings and religious philosophical banter whilst sipping wine by the campfire.
Johnny, every line of code is read several times but written only once. Spending the time upfront to make it readable and understandable is a direct productivity gain.
I found the comment above interesting, having worked on projects where the attitude was âDonât waste time on structure or commenting, do it at the endâ and seeing code written that was good enough simply because it worked, I have found that youâre exactly right. Coming back to the code even weeks later it was incromprehensable, even with an understanding of what the intention of the programmer was. Thereâs nothing quite like seeing âint temp1 = âŚâ to confuse the hell out of anyone trying to read what youâve done.
I would suggest that Johnny reconsider his management style if thatâs his approach; good code structure should be encouraged by management. It takes a little longer now, but in 1 or 2 years when the system breaks down and you need to get a guy in to fix it, you donât want him to be wading through meaningless variable names and weird program structure just to fix a simple mistake.
As a side note, that Perl example makes an argument, but not the one the surrounding text implies. In fact, it might fit higher up in your post, because the correct way to reverse a string in Perl is vastly simpler:
$string = reverse $string;
The join and split operations were probably cargo-culted, and it was the very act of cargo culting that left an obfuscated mess that requires a comment.
Sometimes the best way to be clear when programming a particular language is to learn the idioms of that language well.
Of course, this is Perl, and âbaby talkâ is explicitely allowed â everyone has to start somewhere.
When I was taking programming classes in college, we got hammered if our code was not commented. The idea was to have the how and the why in it, such that it was easy for the grader to skim through the code and tell if it was correct.
Of course, this had a lot of push back from the students who hated wasting time on it. But it did produce code that was understandable by novices.
WellâŚI hate to have to point this out, but the double use of ?: in that example just highlights a bad coding technique. How much clearer would it have been NOT to use the horror that is ?: ?
Itâs describing the code, not the thinking behind it. If you need context for the reverse string operation, why not write a âreverseâ method?