Posted by: terryhowe | October 4, 2009

Clean Code: Comments

I was really curios what Robert C. Martin would say in his book Clean Code about comments. Working with Randall Bryant had made me a believer in almost never using comments and I was glad to see Martin agreed.  Martin feels that comments do not make up for bad code and you should explain yourself in code.  Some examples of good comments include:

  • Legal Comments
  • Informative Comments
  • Explanation of intent if the code does something that looks a bit odd.
  • Warning of consequences
  • TODOs
  • Javadocs in public APIs, but not for everything.

Some examples of bad comments include:

  • Mumbling
  • Redundant
  • Misleading
  • Mandated
  • Historical
  • Closing brace comments
  • Commented out code
  • Java Docs in non-public code
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Categories

%d bloggers like this: