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

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.