Tuesday, 22 November 2011

5 Steps To Effective And Efficient Comments

Recently I visited the dentist for a regular trip to the hygienist. My previous hygienist had moved away and so I had a new one. As part of the visit, my new hygienist said something that got me thinking: "I read your notes earlier and from that...". Exactly what followed is unimportant other than to take home the point that my new hygienist already had an idea of my dental history before they even met me.

Those few words struck a chord with me about how important your comments can be in your code. And whilst the example I give describes when someone else is tackling something you've coded, can you honestly remember every line of code you've written? I know I cant and I can think of at least one occasion where I've revisited a piece of code I wrote, had insufficient comments (that would be none) and could not understand why I had done something in a particular way.

So how do we go about ensuring we give good details about the code without wasting time, effort and the concentration of the reader?

Here are 5 steps I try to follow when writing code:

1. Comment first. Code later

I'm reminded of a quote from a university lecturer after setting us an assignment:

"The earlier you start coding, the further away you are from the solution."

And he was right.

There's nothing worse than trying to work through someone else's procedure that has no comments. Other than your own code that has no comments.

Rather than commenting your code, take the approach of using your comments to describe the approach you're about to employ and then code around that. I sometimes call this: coding your comments.

This forces you plan out your stored procedure. Collect your thoughts and ensure all the parts of the procedure you require are covered off. This approach gives you a chance to spot errors in your logic before you have even begun coding. These comments don't have to be dozens of lines long, and I'd encourage you to try and keep comments short, but ensure its enough so that you can follow your logic and retain your train of thought.

Think of your comments as pseudo code!

Taking this approach you can achieve the following benefits:
  • Sufficient comments for you and your colleagues to follow
  • You plan your procedure before you start trying to write it
  • Potentially spotting issues with your logic before you've even started writing your procedure
Its not a foolproof approach, but I find it saves me quite a bit of time.

2. Provide a clear description

Whenever I open up a procedure I want to immediately know what it does. If you have a good description at the top (in your comment block) it'll be much easier to follow the actual code and understand what is going on. Remember that comments are here to make your life easier - give the reader of the code that chance.

If you can give a good description in 1 line that's fine, but on the other hand don't be afraid to take several pages if needed. If I have to write a long description there's a couple of things I try to consider:

Is this procedure too complex? Should I break it down further? Can I provide a reference to a better description (e.g. a document, wiki article or something with a picture)

If you do still have to write a large amount of text I'll even approach the description/comment block as a document by providing a quick synopsis of the function (often with bullet points) then dive into each of the points after they're listed. Doing this gives the reviewer the choice as to how much they read.

E.g: Consider a poorly constructed database where customer details are stored in many tables and not necessarily with a single "Customer" table. You want to write a customer search procedure but each table stores customer details slightly differently.

Here's what I would write as a comment block:

Performs a customer search with the name provided. We do this by searching the following tables (in this order):
  • dbo.EmailAliases
  • dbo.CustomerOrders
  • dbo.CustomerCorrespondence
  • dbo.CustomerLeads
  • dbo.CustomerArchives
Each table is searched slightly differently, here's how we search each table:

We search this table by comparing the email address supplied. We also try a bit of a pattern search against the names

We search this table by comparing the delivery address and the customer names


3. Only comment as much as you need to

Does the following code really need a comment?
SELECT FirstName, LastName
FROM dbo.Person
WHERE PersonID = @PersonID

Its pretty clear reading the code what that does. On the other hand, I would argue this code does need a comment:
SELECT FirstName, LastName
FROM dbo.Person
WHERE Type = 'X'

Why is there the "WHERE Type = 'X'" in the SQL? If you don't tell people why its there how will we know if its correct or not?

4. Always comment something ugly, non-standard or just plain weird

If I'm reviewing a procedure and I see lots of index and optimiser hints I want to know why they're in there. If you haven't commented a reason to add a NOLOCK hint and I cant see a good reason for it I'm almost certainly going to remove that hint.

Have you applied some business logic to your code? Why is it in there and what does it do? If your code follows best practices and you have a well defined, well normalised schema you'll find you dont have to provide many comments at all. If you're the other 99% of us that don't have that luxury you'll find comments invaluable when you come to fix something later.

5. Do not comment out blocks of code

If its not needed...take it out completely! Don't comment it out "just in case" you need it later. Use source control rather than commenting out sections. Thats what source control is for! Its just as easy to redeploy an old version of a procedure as it is to uncomment a piece of code. Because its the same function! I have seen procedures that are comment blocks and no runnable code. Worse still - there was no comment about why something was commented out!

If you feel you absolutely must comment out a section of code, at least put a comment alongside it with a date at which point that block can be considered dead and fully removed. And add a reminder to your calendar!


Most technology people hate writing comments, we just want to code and code quickly. Some people even argue your code should be obvious enough to negate the need for any comments. If you can do that then great! But in my experience, and especially with TSQL, its rarely possible to do that. Like my new dental hygienist who hadn't put eyes on my teeth before, and who will almost certainly look at many more sets of teeth before mine again, notes and comments help you get an idea of the task in front of you. Hopefully one or two of the points will help you quickly write clear and concise comments without taking up much of your time.

No comments:

Post a Comment