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

Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s


%d bloggers like this: