Best Practices for Comments on Code Commit

Question

What template do you use for comments on code commit?

One example of a template is:

1. (change 1): (source file 1.1, 1.2): (details of change made), (why)
2. (change 2): (source file 2.1): (details of change made), (why)

Ideally each change should be mapped to an issue in the issue tracker. Is this template alright?

Answer 1

Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.

Answer 2

I try to keep my fixes in separate check-ins.

I don't use an actual template, but a mental one, and it's like this.

Issue - dev level summary of issue.

The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.

Answer 3

I try to follow the same rule as for code comments:

Explain the WHY, not the HOW.

IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.

Answer 4

If you use a bug tracking system, include relevant ticket numbers.

You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.

Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).

Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).

Answer 5

Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.

• You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
• I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
• A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
• Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.

Given these ideas, an example commit comment for me would be something like

Req3845: Updated validation to use the new RegEx validation developed in Req3831.

Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.

Answer 6

There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.

Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.

Answer 7

Here's what I've seen used successfully:

• Reference to bug number or feature ID
• Brief description of the change. What was changed.
• Code reviewer (to ensure you have one) unless handled by the checkin system.
• Name of tester or description of which tests were run (if late in the process and you are being extra careful)

Answer 8

I use the simple technique described by Chaosben on the JEDI Windows API blog.

In order to get a fast view on the changes made to a repository, we suggest to write brief concise comments starting each line with one of these chars:

• + if you added a feature/function/…
• - if you removed a feature/function/bug/…
• # if you changed something

Doing it this way, other developers may find the desired revision much better.

Answer 9

I prefix each paragraph with + - * or !

+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix

I don't think you should commit detailed description about what parts of the code are changed, cuz, thats why every VC has diff :)

Answer 10

If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change

Answer 11

First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.

I think that commit message conventions expected and used by git makes much sense:

• The first line of commit message should be a short description
• If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
• In next paragraph or paragraphs describe the change, explaining why's and how's

Answer 12

Thilo,

Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).

Any efficient way to do that?

I mean by that I understand what it is about and my question target the fact that when a file has all un-commited changes done and the moment to commit happen, How do you do two commits with one file?

Example:

• 2 new features in a myClass.cs
• myClass.cs in the repository does now have these new feature committed.
• myClass.cs in the working directory has both of them.
• I want to enter 2 commit message foreach features.

thanks.

jgi