Question

I am maintaining a large asp.net app.

My objective is to identify the lines added in response to particular tickets. While it is possible using our SVN, I want to put it in the code. because these changes would look just odd to a first time reader of the code.

So which outlining method is more suitable for this purpose

{
//response to ticket #xxxxx
...
...
..
}

OR

#region response to ticket xxxxx
..
...
..
#endregion

Or is there any other method more suited for this

Answer 1

Between the two, definitely use comments – they are very flexible. Regions are no good for this sort of thing – what if multiple tickets require code changes which overlap? That’s easily explained in a longer comment.

However, I’d argue against putting this kind of info in the comments anyway. No one is actually going to stumble onto code written a year ago and go look up the ticket. Code should be self-explanatory, and in the very odd case where it is not, comments should describe what the code actually does, not why. To address your specific concern of new readers – your colleagues do not need justification for why code is the way it is. They will assume it is that way for a reason, and when making additional changes will always try to maintain the existing functionality. That’s basic professional behavior.

Your changeset should be associated with the ticket # in case anyone needs historical information. There’s a list of justifications for why things are they way they are stored on each file. That is stored external to your codebase – either in your source control or some other repository.

In my experience, putting ticket numbers in the code is usually a symptom of bad practices. It denotes a deviation from the design instead of fixing the design. A ticket number says “this is how the code was, and this is how it is now.” Codebases should not reflect their own history – all that matters is how they work right now.