How often to comment when committing code? [closed]

Question

What are best practices for COMMENTING commits?

A little background.

• All our projects use version control (Subversion / SVN / Git),
• Most of them are touched by 2 or more developers,
• We use Springloops to host our version control, since it "just works" and is cheeper than having an internal dev maintain it,
• Because so many of our clients have special setups and since it's work to set up these environments for multiple users, we rarely bother with a local dev environment. Most clients have a dev location in the cloud and then a live location. Springloops is configured to automatically push EVERY commit to dev server, and devs must manually push to the live locations.

Our policy has been to comment EVERYTHING you commit, but a few of us have recently rebelled against that idea.

The problem with commenting everything is two fold, it's more work, and less useful. Here are the problems we see:

1. It encourages people to make comments which cover things that are already in version control (i.e. I changed line 42 to do blah). You can just compare to get the same info!

2. Alternately it will fill up your comment stream with useless comments which are a HUGE pain if you ever want to search through the comments.

   • Margin problems with IE8
   • Another fix to margin in IE8
   • Reverting that last fix and trying something else with margin in IE8

Either of these things just adds a lot of time, and doesn't add any value. Comments are only useful if they're specific enough and rare enough that you can scan everything.

We've been told that Git handles this in a smarter way than Subversion and we're open to changing, and obviously having a local development environment and only committing batches of changes would also help, but based on our use case that would probably be a net loss in terms of efficiency.

I'd love to hear what are people's best-practices for commenting commits, thanks for any feedback!

Answer 1

Git won't solve the problem for you; you need to answer this "simple" question: How can you increase the value of comments?

Some guidelines:

1. Don't mention anything in the comments which is obvious from the commit itself (like which line was changed). Modern tools will show the commit message and the commit side-by-side on the screen. There is no point to duplicate work.

2. Instead, explain why you made the change - this is usually not obvious. Was it a bug report? Include the ID of the bug. Was it something you found?

3. If you find yourself often in a situation where you have to commit several fixes in one commit, then you need to learn to focus. Don't follow every whim as you change the code. Do one thing, finish it, commit it. Then do the next thing.

   If you stumble over something on the way, make a note (on paper or in an extra text editor which you keep hovering in a corner of the screen). Don't always interrupt your work! Multitasking / recursive code editing has a severe impact on quality and stress levels.

You will still get long lists of "Fixed IE8 margin" commits but that in itself isn't a problem. When you say "we want to search through the comments", you must come up with a way to put useful information into the comments to make it reasonable to search on them. For example, always use the same format for bug IDs. Plain text is bad for searching, especially commit messages which should be concise.

Just omitting comments isn't a solution, it's either laziness or a sign of being a sociopath ("who cares if someone else has a problem with that?") or bad training ("I have no idea what to write").

The first and last can be solved with training. The second one by getting rid of a risk (i.e. firing the guy).

No version control tool in the world can help you there.

Answer 2

My rule of thumb is that if I can't summarize a commit's changes in less than two sentences its been too long since the last commit.

And As far as what to write in that sentence I never say anything line specific or file specific since that information is embedded in the commit. I normally mention the specific change in plain english like I would explaining it to someone that wasn't part of the project.

This works really well because whether its me or someone else months later they can read the commit logs like a story of how the project developed. I've even done blog posts that were just copy and pastes of my commit logs.