We need to develop guidelines for writing comments when we register code in version control system (such as TFS).
E.g., when we submit a bugfix, we create a comment "Fixed bug #..."
We tried to brainstorm on this topic, but most of the ideas bring too little added value.
I would appreciate any suggestions for this.
Generally the comments we do where I work are a quick overview of the changes that were made. Something short and simple.
It may not seem to add much value initially, but can be very helpful when going back through history trying to find when something changed (much more so than just "bug #####"). There have been a few times when I needed to go back in the source control history to try and find when a particular behavior or piece of code changed, and the quick overviews can make it much easier to track down where that might be. If you just give a bug number then you have to do more work to find that basic information (pull up bug tracker and find the bug).
If the change has an associated ticket somewhere or a bug, in that case the number and title (with a link) should be enough.
Otherwise just state what change did you implement. Regular commenting guidelines apply, you can check some popular project log to see good examples.
I like to include a reference to the bug (ticket, issue, what ever its called) if possible because that provides the context and motivation for the change. Also, I like to try to answer the questions What has changed and Why in as close to one line as I can. When doing the comment, I try to think about my future self in 6 months looking back at the logs, diff, and ticket to understand what the heck I was thinking. Getting into too much detail never seems to help.
You can configure TFS to require that any code check-in have a TFS task associated with it.
The project team that uses it where I work requires that all bugs and / or features be entered in TFS as tasks - and that any code check-in be associated with the tasks(s) that it applies to.
A comment is also required but they don't have any stringent guidelines for what you write, except to note if the change is not required to be merged forward to another branch.
Ron
For a change that will be mentioned in the Release Notes, include a suggested Release Notes entry, either in the changeset comment or in the linked bug report if there is one.
By writing out a Release Notes entry, you're forced to take a step back and look at the edit from the user's point of view. This encourages you to succinctly describe what the problem was and how the fix addresses the problem.
My (rather pithy) guidance around this topic is "to document why you are making the change not what."
I.e. you shouldn't say "fixed bug in MyClass.cs and FooBar.cs" because that comment is fairly irrelevant - they can just look at the changeset to find those details. Equally with TFS the linking of changesets to work items means that including the work item reference in the comment is pretty superfluous. Instead a short sentance explaining the reason for the change such as "fixed potential XSS vulnerability in editor" is the most useful thing to read when looking through a big history of changesets.
Where possible (such as when using TFS for bug-tracking and source control) link the checkin directly to an appropriate work-item. Failing that, add the work-item / bug # in the changeset comments. This is the bare minimum acceptable level of changeset comments.
The checkin comment should describe the intent of the change made, only adding details on the way the change achieves the desired results as necessary. A good starting point would be the title of the appropriate work item.
One or two sentences is a good target length for the comment. Don't be so general the comment is meaningless (e.g. "Fixed a bug in xyz"), but don't hide the intent of the change under layers of unnecessary detail either.
+1 for pasting the bug issue title, which should be informative.
+1 for document why, if needed in addition to bug title.
+1 for being conscious about release notes for when you want to inform customers.
+1 for integrating SCM, bug tracking, and CI, and making them link to each other on issues/ bugs.