C# outlining. braces or regions

Question

Hi

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.

Answer 2

Try a few and see what your colleagues think.

For anything but the more trivial changes you're most likely to have alterations scattered through your source -- so using SVN blame / annotate is going to be the best bet.

Answer 3

We use JIRA plug-in for SVN to directly see what code files have been modified for a particular ticket.

Regions might become cumbersome as ther could be a case where one line of code is used to fix two tickets. So, pick the first one //ticket #

Answer 4

The first option. "//response to ticket #xxxxx"

The first time you do this...

int defaultVal = 12;

To this...

int defaultVal = 13;

You will hate your life if you decide on a #region paradigm. One/two line code fixes are the norm, and I know from experience that overuse of regions messes with your visual flow by hiding data unnecessarily.

It would be better to do this to hide the items you KNOW are crap.

#region Old Code
//int defaultVal = 12;
#endregion
int defaultVal = 13; //Changed by Ticket:13414

This leave the new code visible by default, and the old code hidden.

Answer 5

Response to Option 1: Adding comments for tickets would decrease the readability of code. I think (and this is encouraged at my company) that when you check in a ticket-fix, you should also document that section of code more appropriately, but again, adding a ticket number might just be confusing.

Response to Option 2: Regions are for grouping functions with similar purpose together, so I would not recommend this option either.

Proposed Option: Use the /// standard of commenting functions and add a This is what was changed. element. This way fixes don't disrupt the normal readability, but it's simple to see functions that were involved with tickets. As an added bonus, this mechanism is self-documenting, so these would automatically get put into your generated documents. Note: You might want to check that custom tags are supported.