Computer Science
Clean Code
Comments

Comments

Good Comments

  • Legal Comments: For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.
  • Informative Comments: they are sometimes useful, but it is better to use the name of the function to convey the information where possible
// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
"\\d**:\\d**:\\d** \\w**, \\w** \\d**, \\d*");
  • Explanation of Intent: comments that provide the intent behind a decision.
//This is our best attempt to get a race condition
//by creating large number of threads.
for (int i = 0; i < 25000; i++) {
  WidgetBuilderThread widgetBuilderThread =
  new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
  Thread thread = new Thread(widgetBuilderThread);
  thread.start();
}
  • Clarification: In general it is better to find a way to make that argument or return value clear in its own right; but when its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.
  • Warning of Consequences: Sometimes it is useful to warn other programmers about certain consequences.
// Don't run unless you
// have some time to kill.
public void _testWithReallyBigFile()
{
...
}
  • TODO Comments: Still, you don’t want your code to be littered with TODOs.
  • Amplification: used to amplify the importance of something that may otherwise seem inconsequential.
String listItemContent = match.group(3).trim();
// the trim is real important. It removes the starting
// spaces that could cause the item to be recognized
// as another list.
  • Docs in Public APIs: If you are writing a public API, then you should certainly write good javadocs for it.

Bad Comments

  • Redundant Comments: comments that are not more informative than the code itself.
  • Misleading Comments: that say half truths and may confuse future maintainers.
  • Mandated Comments: It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment.
  • Journal Comments: Sometimes people add a comment to the start of a module every time they edit it. They are no longer necessary as we already have version control.
  • Position Markers: A banner is startling and obvious if you don’t see banners very often. So use them very sparingly, and only when the benefit is significant. If you overuse banners, they’ll fall into the background noise and be ignored.
// Actions //////////////////////////////////
  • Closing Brace Comments: Sometimes programmers will put special comments on closing braces. It serves only to clutter the kind of small and encapsulated functions that we prefer.
  • Attributions and Bylines: Source code control systems are very good at remembering who added what, when.
/** Added by Rick **/
  • 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.
  • 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 a local comment.
  • Too Much Information: Don’t put interesting historical discussions or irrelevant descriptions of details into your comments.
  • Inobvious Connection: The connection between a comment and the code it describes should be obvious.
  • 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.
  • API Docs in Nonpublic Code: Generating javadoc pages for the classes and functions inside a system is not generally useful.
FunctionsFormatting