(2003 to 2005)

Commenting code sections

Mon Jan 26 19:18:00 UTC+1100 2004


I'm a bit of a pedant when it comes to laying out my code. I'm one of those guys that gets someone elses code and then spends the first 10 minutes renaming all the variables and moving the various code members around.

I used to work with a bloke called Phil and he was an IBM hardware guru, I was having some trouble with a RAID adaptor that I was installing in a test machine and I got him to help me with it (you know, getting favours in the corridor style). He remarked to me “standards are great, isn't wonderful that there are so many of them!”, which was of course a bit of a joke and quite humorous. Anyway, that little line stuck with me, and it pretty much sums up where I am with my coding conventions.

I've been coding in C# for years. My coding style has certainly evolved quite a bit over that time. Recently I've decided to make another change. This one is pretty minor though.

I have a pretty rigid method for laying out the various class members in a class. I stick this stuff inside region tags, along the lines of 'Private Variables', 'Properties', 'Constructors', 'Public Methods', etc. I then put in a section heading, sometimes several per region, sometimes only one per section, for example I might have 'Private Variables' and 'Designer Variables' sections in the 'Private Variables' region, or just 'Private Variables' depending on how useful it is to seperate stuff out.

Anyway, I have a few macros in Visual Studio that I wrote to make this easy for me, and I've bound some shortcut keys to these, so I can press CTRL + =, CTRL + L to insert a section comment. A little box pops up and asks me to enter a name for the section and then it prints the section at the current location, which is kind of cool. I use to print section headings like this:

     *                        ---------------------                         *
     *                          Private Variables                           *
     *                        ---------------------                         *

but I've recently changed my mind, and decided that this is better:

    //                       ---------------------                          //
    //                         Private Variables                            //
    //                       ---------------------                          //

To start with I think it looks a little nicer, but apart from that I've decided to walk away from the /* */ comment delimiters. The problem with these is that they don't nest. So if I want to comment out a section of code temporarily that spans regions or sections I can't use the /* */ syntax. This isn't really a big deal, since I usually use CTRL + K, CTRL + C and CTRL + K, CTRL + U to comment and uncomment sections using the line comment // syntax, but nevertheless, now I have more options, and options are good.


Copyright © 2003-2005 John Elliot