Clean Code — Comments (Summary)
Comments are important things in programming. A well-placed comment will be so helpful for a programmer, on the other hand, the frivolous dogmatic comment will be so damaging and might give misinformation. But we don't need to use comments if our code is clear enough and can tell “a good story” about a block of code.
Comments Do Not Make Up for Bad Code
The common reason a programmer use comment is to explain a bad code. But it’s a bad habit, we had better clean it rather than commenting on a messy block of code. Clear code with a few comments are far better than cluttered and complex code with lots of comments.
“Don’t comment bad code — rewrite it.” — Brian W. Kernighan and P. J. Plaugher
Explain Yourself in Code
We should rewrite our code rather than give an explanation in a comment. See the difference:
and
It’s simply a matter of creating a function that says the same thing as the comment we want to write.
Good Comments
Some comments are necessary. But keep in mind, the only truly good comment is the comment you found a way not to write.
Legal Comments
Sometimes, the corporate forces us to write certain comments for legal reasons. For example copyright and authorship.
As much as possible, refer to standard license or other external documents rather than putting all the terms and conditions into the comment.
Informative Comments
It’s useful to provide basic information with a comment. For example, the input format of function.
Code above explains that the regular expression is intended to match a time and date, and the function using the specified format string.
Explanation of Intent
Sometimes a comment is used to explain the intent behind a decision
Focus on the comment that the programmer trying to explain why he choose that number.
Clarification
Sometimes it is just helpful to translate the meaning of a block of code into something that’s readable. In general, it is better to find a way to make that a block of code clear in its own right.
Warning of Consequences
It is useful to warn other programmers about certain consequences. For example:
Again, It’s better to solve the problem. But the comments are reasonable, it gives warning to a programmer.
TODO Comments
When there are jobs that the programmer thinks should be done, but for some reason can’t do at the moment, it’s good to leave some “To do” notes in the form of //TODO comments. //TODO comments can give a message about what the function’s future should be.
Amplification
A comment may be used to amplify the importance of something that may otherwise seem inconsequential.
Bad Comments
Mumbling
If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write and will not give an obscure understanding to the reader. Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes.
Redundant Comments
That comment is completely redundant. It might take longer to read than the code itself.
Misleading Comments
Also, the comment in the previous picture was misleading. The method does not return when this.closed becomes true. Otherwise, it waits for a blind time-out and then throws an exception if this.closed is still not true.
Mandated Comments
It's a bad idea to have a rule that says that every function must have a javadoc, or every variable must have a comment. Comments like this just clutter up the code, propagate lies, and lend to general confusion and disorganization.
Journal Comments
* Changes (from 11-Oct-2001)
* --------------------------
* 11-Oct-2001 : Re-organised the class and moved it to new package
* com.jrefinery.date (DG);
* 05-Nov-2001 : Added a getDescription() method, and eliminated * NotableDate class (DG);
* 12-Nov-2001 : IBD requires setDescription() method, now that
* NotableDate class is gone (DG); Changed
* getPreviousDayOfWeek(), getFollowingDayOfWeek() and
* getNearestDayOfWeek() to correct bugs (DG);
* 05-Dec-2001 : Fixed bug in SpreadsheetDate class (DG);Long ago, when we didn’t have version control systems, the journal above might be helpful. Nowadays, these long journals are just more clutter to obfuscate the module
Attributions and Bylines
/* Added by Rick */Same as before. version control systems are good for remembering who added what, and when.
Commented-Out Code
Others who see that commented-out code won’t have the courage to delete it. They’ll think it is there for a reason and is too important to delete. Again, we have a good resource version control system. Those systems will remember the code for us. We don’t have to comment it out anymore. Just delete the code.
Noise Comments
From the picture above, noise comments are bad, doing nothing, and provide no new information.
Scary Noise
Javadocs can also be noisy. They are just redundant to provide documentation.
Don’t Use a Comment When You Can Use a Function or a Variable
Consider the following stretch of code:
This could be rephrased without the comment as
Position Markers
// Actions //////////////////////////////////Maybe you have seen a position marker like that. Actually, you don’t see position markers very often. So use them very sparingly, and only when the benefit is significant. Otherwise, they’ll fall into the background noise and be ignored.
Closing Brace Comments
Sometimes programmers will put special comments on closing braces. So if you find yourself wanting to mark your closing braces, try to shorten your functions instead.
Nonlocal Information
If you must write a comment, then make sure it describes the code it appears near. Don’t offer systemwide information in the context of the local comment.
Too Much Information
Don’t put interesting historical discussions or irrelevant descriptions of details into your comments like the example below.
/*RFC 2045 - Multipurpose Internet Mail Extensions (MIME)Part One: Format of Internet Message Bodiessection 6.8. Base64 Content-Transfer-EncodingThe encoding process represents 24-bit groups of input bits as outputstrings of 4 encoded characters. Proceeding from left to right, a24-bit input group is formed by concatenating 3 8-bit input groups.These 24 bits are then treated as 4 concatenated 6-bit groups, eachof which is translated into a single digit in the base64 alphabet.When encoding a bit stream via the base64 encoding, the bit streammust be presumed to be ordered with the most-significant-bit first.That is, the first bit in the stream will be the high-order bit inthe first 8-bit byte, and the eighth bit will be the low-order bit inthe first 8-bit byte, and so on.*/Inobvious Connection
The connection between a comment and the code it describes should be obvious. Make sure the reader be able to understand what the comment is talking about.
Function Headers
Short functions don’t need much description. A well-chosen name for a small function that does one thing is usually better than a comment header.
Javadocs in Nonpublic Code
Generating javadoc pages for the classes and functions inside a system is not generally useful, it will give little more cruft and distraction.
These are all Chapter 4 summaries of the book that I have been trying to learn and got the point of the book with the title “Clean code” by Robert C. Martin.
Feel free to give some suggestions and feedback. Thanks.
Reference
“Clean code” by Robert C. Martin
