Commenting Your Code

At my last job, I was the IT Manager.  I oversaw anything that had to deal with IT, but most of my time was spent reviewing TSQL code created by the programmers.  One of our programmers was horrible at making notes in her code (and by horrible, I mean she didn't do it at all).  When I had to review the code, I had no idea what specifically she was trying to accomplish.

One SQL project she was working on dealt with rating our customer's calls.  Since our rating was quite complicated, so was the code.  Reviewing her code was a long and arduous process and since her program didn't work they way we wanted, I had to inspect each and every single line of code.  Some of the suggestions from the following article would have helped:

TSQL Coding Styles

Some different things I did while going through her code:

• Comments
• With each line of code or query I made a comment about what exactly that code was doing.  I used /*.......*/ for long notes and -- for short notes
• These notes can be pretty short and to the point, just so people know what it's doing.
• Formatting Code
• I like to put my SELECT, FROM, WHERE on their own lines
• I like to put only about two conditions on a line, depending on how long a condition is
• Naming Guidelines
• Unfortunately, I was one of those people who would use table and column aliases that weren't descriptive.  Code is much easier to look at if the aliases give a little information about what the data actually contains
• Variables with descriptive names are very important, especially for long code.

I promise you that if each of these guidelines are followed, your code will be easier to read and debug, not just for you, but anyone else who could possibly read your code.