SubVersion Comment Standards

.NET
1

Does you or your team have any comment standards when it comes to checking in source?

We've always commented as we like

Reason I ask:
I was asked whether we can tell if the source changed as a result of a bug fix, or change. i.e if someone asked when was a certain bug fixed I could give them the revision, person, date and what was/wasn’t included.

I was asked if there would be any value in implementing some comment standards and I couldn’t argue the case against. If the first line indicated “BUG: Ticket: 65748” we could instantly tie the work back to a logged ticket.

It would make reviewing comments easier too since all would be of similar format. The small overhead os obviously when checking in source.

2

^^^^You don’t even need EAP, just grab the beta of resharper. They are also selling licenses now (just upgrded us to 5 yesterday, w00t).

3

The latest version, Resharper 5, supports VS2010. It’s still in development, but you can get access to it through a Early Access Program: http://confluence.jetbrains.net/display/ReSharper/ReSharper+5.0+Nightly+Builds

I highly recommend taking it for spin, it makes a huge difference to the IDE experience! So much in fact I can’t use Visual Studio without it!

4

One technique I use is the “search on page” feature in some text editors/IDE’s. You could also do it is CSS, Javascript, .ect.

Use this to find bugs that need to be fixed:


//#&

Use this for code that has changed.



//#@

You get the idea. Just remember the unique codes for different searches in the document. The search feature makes it way easier to find things in thousands of lines of code, instead of scrolling.

5

I usually use commenting to help explain what the code is actually doing, and why it’s doing it a certain way, leaving Changes, Bug Fixes etc to Source control.

A product like SourceGear Fortress is great for source control and bug tracking, it’s free for a single user if you want to try it out.

6
  • edit: nevermind, I misread your post
7

I try to keep my check ins small, and use the message to describe what I just did and why. If your working on a ticket, including the ticket Id is a good idea. Having your bug tracker hooked up to your VCS with some kind of convention for comments is also a good idea. Say having something like: “Closes #1234” that automatically sets the ticket to closed and associates the check-in what commit is invaluable.

Do you use Reshaper? It has a Todo lsit functionlity that allows you define regexp to track and list comments. So you can set it to track and list things like: // BUG: // HACK: //TODO: etc.

8

Think there may have been some misunderstanding. DHTMLGOD seems to have understood though. I was talkign specifically about comments when checking in code, not inline comments.

After creating the thread I did start reading about SubVersion and the possibilities that exist. Seen that tortoise can integrate an issue tracker. At it’s simplest it can store a bug (ticket) id, after setting some properties on the repo. This at least lets check-ins be associated if required to an issue. Even provides a link to the issue tracker.

Further reading led me to gurtle and other plugins that allow issue tracker integration. i.e search and select. I presume also as you mention “closing of tickets too automatically”. I may look into this although it would require me to build one to work with our issue tracker.

9

Standardization would be cool. These days, I’m happy when I get people to comment at all.

Personally, I try and either give some idea what the checkin was about, or if there is an issue# or something, etc. No real standards though.

10

Dhtmlgod, no I have never used ReSharper, but I have heard of it in this forum. If I am coding in Dreamweaver, I use their built in functions. Haven’t been coding as long in .NET as you probably have. but I will defiently give it a look now. I’m sure it will be supported in VS2010…