A guide to commenting code

One of the most important things in programming is correctly and effectively commenting your code.  Comments exist in most programming languages and serve as a means of leaving yourself and/or others reminders or explanations of what your code is doing.

In this article I want to talk in more depth about the importance of code commenting, as well as highlighting what I consider to be some useful tips and general no-no’s

Commenting code is one of those things that seems like a great idea, but in my experience not enough people do it, and those that do don’t often do it well enough.  I’m even guilty of under-commenting the work I create, and have fallen foul of my lack of comments when revisiting code I haven’t looked at for some time.

So, why bother?

Commenting code should be used as a means of explaining what your code does.  Particularly complex statements or expressions should have some kind of comment to accompany them to explain what it is that they are doing.  How many times have you had to work on or fix up some code you’ve written months ago only to look at it and wonder where the hell your head was at at the time of creating it?  Code comments can act as a simple memory jog to your future self regarding exactly what you were thinking.

Is there a particular standard way I should comment?

No, not really, but I would say there are some general guidelines you should follow.  Depending on who you are working with (if in a team) there might be some kind of in-house standards that are expected of you.  As an example, in my organisation we are looking at standardising coding practises across the patch, and one of these standardisations involves the way we comment our code.  At the top of each module or section of code written, we would usually expect to see something like this:-

/*

Title: parsedata.asp
Author: M.Richardson
Date: 15/02/2012
Purpose:  To parse xml data based on criteria supplied by a querystring from reports.asp
Last revision: 23/06/2012

*/

Now, this is a fairly straightforward template that briefly explains the purpose of the whole script that I have created. It makes it easy for me (and others) to open and see a brief overview of what that script does.  Simple enough, isn’t it?

The only problem with this kind of ‘code header’, however is that it can be open to some flaws.  Let’s say for example that a colleague decides that the code in this script could be useful for another area in our application, but it needs a few tweaks or additions.  In this case she might copy and paste the file and rename to something else, make her changes and deploy.  But what if she neglected to change the header comments?  The new code now has incorrect information in it and later down the line that could cause some serious confusion.

My advice is this – if you are going to use code header comments in this way, get into the habit of checking the information in it before you save..  You’ll thank me later.  Really, you will.

Code headers can be useful for a lot of things, and there are no hard and fast rules for what to include in them.  In my example I’ve included a ‘last revision’ heading.  I’ve actually put that there on purpose to make a point. I never add this information. Once again, if it isn’t updated every time the code is changed it is useless data to store, and secondly, if you are using source code control of any kind (Git, Mercurial, etc), all of your revision metadata will be stored in your source code repository.   Think of it almost as a separation of concerns – in your code, your comments should be about what the code does, not when it was changed.

A colleague of mine actually used to use commenting to make note of revisions made to his code, including dates when new statements have been added, removed or altered.  Again, this is something I would urge you not to do.  It can bloat your code, unnecessarily increase your file size, and again, if you use source code control you have the entire history of your file stored in your repository.  Keeping your code comments relevant to the task and to the point will benefit you and others in the future.

As far as I’m concerned, you can comment as prolifically as you like, as long as your comments are helping you or others to understand what it is your code/markup/css is actually doing.  I occasionally use code during development to remind me that something might need to be changed at some point in the future, or use it to add inline ‘to-do’ notes as ideas come to me, but I always ensure that these are removed when my final code goes live.  The only comments I then keep are those that explain the purpose of my work.

A great example of extremely well-commented code for your perusal is jQuery (follow this link to see for yourself).  Pretty much everything is commented so it’s easy to see what everything does.  This use of commenting is actually in some ways as useful as the documentation, as you can see how everything is intended to be used in the code.  If you can comment your work anywhere near as clearly as this you are doing a great job.

I hope this has been of some use to you.  Do you have any particular standards you use when commenting your work, or is there anything I’ve missed out?  Let me know in the comments!

Leave a Reply

Your email address will not be published. Required fields are marked *