When a comment is needed for clarity, the ExtremeWay is to improve the code until, ideally, it no longer needs a comment. Understand what it is ToNeedComments.
It's not always possible to rewrite unclear code. Examples:
-- FreddyTheCat?
Explaining the programming language isn't one of the exceptions. It's OK to assume competence but not wizard status. On the other hand, using the most obscure form of the language isn't OK either. If the idiom is important and not uncommon, use it. Give the method a decent name, sort of like (someone correct my code, I'm just typing this in)
copyToNull (char* In, char* Out) { while( *Out++ = *In++ ); }Similarly, let the code say that it's optimized:
exportEmployees employees do: [ :each | each exportOptimized ]I'd suggest that something like this makes it clear you don't want to screw with the code. -- RonJeffriesEmployee>>exportOptimized self exportPersonalBuffered. self exportDollarsBuffered.
Employee>>exportPersonalBuffered | bufferedPersonData | bufferedPerson := self getPersonalData. bufferedPerson exportName. bufferedPerson exportAddress. bufferedPerson exportPhone.
Employee>>exportDollarsBuffered etc ...
Bjarne Stroustrup says in "The C++ Programming Language" (3rd Ed., Chapter 6.4):
To pick up your code example, the "optimized" in exportOptimized is ambiguous. It can refer to the action done, or to the way the code is written. The latter usage smells, like HungarianNotation, and is exposing implementation details. If I see a name like exportOptimized, I assume the function exports something in an optimized form (e.g. a database without deleted records), I don't recognize it as a warning not to meddle with the code. See also Clear Warning in MethodCommenting.
I don't want to duplicate MethodCommenting and ToNeedComments here. Many caveats about TreatCommentsWithSuspicion that are in my mind now are expressed there, in the patterns at the beginning.
Just now I stumbled over a possible reason as to why I oppose TreatCommentsWithSuspicion and "Do not comment bad code, rewrite it.": Both statements are negative. How about "If you can turn a comment into source code, do it."? This guideline is based on the Stroustrup quote, but goes farther, as the quote doesn't say anything about removing the comment. With my proposed guideline, there is less danger of losing information when removing comments, a danger I see with the more urgent statements above. <sarcasm mode> But maybe the sense of urgency lies within me, because I am one of those rule-obeying Krauts :). </sarcasm mode>
A good partner for "If you can turn a comment into source code, do it." would be: "If you can make code clearer, do it. Even if you just add a comment.". This also goes with NanoRefactorization.
-- FreddyTheCat?
I like the positive form. The partner rule I cannot support. It's easier to add a comment than it is to fix the code, but fixing the code is the right thing to do whenever possible. I would choose not to recommend the easy but wrong fix. Prefer telling people they can't comment unless all else fails ... because it rarely does. -- RonJeffries
I usually use a multi-phase approach. Every time there's some code that's unclear, I comment it. Then, every time I run across a comment, I see if there's an ExtractMethod or renaming I could do to make the code say exactly the same thing as the comment. Then once I get code that looks like this
// Load register state for current process currentProcess.loadRegisterState();I remove the duplication by deleting the comment (unless I have a professor that grades based on number of comments...yes, I've had some. ;)).
I tend to get better naming and more SelfDocumentingCode this way, because I'm writing first for the human and then turning the human code into something the machine can read. It's the same reasoning behind MakeItWorkMakeItRightMakeItFast. Focus on achieving the goal (clarity) first, and then refactor so there's no duplication.
-- JonathanTang
Almost every sort of collection in Java is 0-based. The notable exceptions are the JDBC API and Record stores. Every time I have cause to iterate or select by index in one of its one-based collections, I comment it. Mostly to remind myself that these are the exceptional cases and I can't be sloppy. -- StevenNewton (and KarlKnechtel)
Are comments SignOfInsecurityInCode?
This page mirrored in WikiPagesAboutRefactoring as of July 17, 2004