Usable Subversion Comments

I notice that when I am browsing subversion repositories, many times depending on the culture there can be little in the way of usable comments, and depending on the number of individuals the format and style of these comments can vary wildly, I was even looking back at some of my worst offenders, blank, or fixed this. Even the comments that are always there, do little in the way of telling you what happened with out viewing the changes.

Example of useful source control comments:

Line 1: Subject of the change, this will show up in the log view when using tortoise, so it becomes important that this summarize the changes in a succinct manner.

ex. Updated Login, fixed bug, and changed validation.

Line 2 and below, this becomes a list of specific details using ordered or unordered format, but the important part is very discreet comments, but not so detailed it drowns out the usefulness. List major fixes, or if it needed to be re-factored, just say that.

List of details.
1. Error in if statement, fixed logic.
2. Username was being passed…

This should provide scan-able, readable, and ultimately useful comments when committing to revision control.

Example of complete comment:

Updated Login, fixed bug, and changed validation.

List of details.1. Error in if statement, fixed logic.2. Username was being passed as password to Login.RoutineName, changed to pass correct parameter.3. Changed validation of to allow non alpha numeric characters in user name.

Part 2: Naming Convention

This entry was written by admin, posted on Jul 23 at , filed under comment, documentation, source control, svn. Bookmark the permalink. Follow any comments here with the RSS feed for this post. Post a comment or leave a trackback: Trackback URL.

Post a Comment

Your email is never shared. Required fields are marked *

*
*
Profile Picture

About Ian Lintner


I am a software developer, mostly web,  in Des Moines, Iowa. I take a very opinionated stand concerning development, you will never regret a simple design or architecture. My education was at Drake University in Biology and Computer Science. Offline I am recently married to my wife Heather. I try my hand at many hobbies currently I am gardening till the snow comes in.



My Current Projects


Des Moines Twitter Trends