Good and Bad Code Comments

Good and Bad Code Comments

March 3, 2011

Chapter 8 – Open Teams

Check-in comments are a good representation of what you do every day. Good check-in comments will give you and your team the information you need to understand the changes you are making. Bad check-in comments will make your version control history useless. Productivity for engineers is often measured by the code they produce, but that productivity can be difficult to track. The number of lines written or number of functions implemented are not useful metrics. Looking at check-in comments is an easy way to track the progress of individuals when they are writing code.

The first step is to ensure that every time someone checks into the version control system they provide a comment. Many organizations don’t enforce check-in comments and many engineers forget to add them. Every single check-in you make should have a comment. It doesn’t need to be paragraphs long, just enough to get a quick idea of what changed and why you changed it.

A good check-in comment will give the reader a quick understanding of the change that was made.

Check-in comments should

  1. Give a simple and straightforward explanation of the change.
  2. Be written in complete sentences.
  3. Talk about why you made the change and not just what you changed.
  4. Mention other people who helped with the change.
  5. List the numbers for the relevant bugs.

Check-in comments should not

  1. Be empty.
  2. List just a bug number.
  3. Give formatting descriptions like: “changed two lines”
  4. Make sense only to you.
  5. Document every single change made to the file.

Previous post:

Next post: