Code Comments

By Justin
Posted on Jun 24, 2008

Comments (0)

There are generally two camps of thought when it comes to comments: (1) some people stress that they be used often and fairly heavily, and (2) others will advise that they are best not to be used at all except in very complex situations where some object, method or algorithm simply needs to be explained. In practice however, the use of comments typically falls somewhere in between. In the end, experience is the best determinant when it comes to using and managing code comments.

The following are my recommendations regarding the use and management of code comments based upon my experiences in a wide variety of projects both large and small.

Generally speaking, I tend to discourage the use of comments, primarily because I've found that programmers often do not update them when code changes later in a project. Without proper maintenance, the end result is a bunch of comments that no longer match the code, leading to confusion and wasted time. Interpreting someone else's code can be hard with good comments, but it's just plain frustrating when the code is peppered with outdated comments that no longer accurately describe the code's purpose. Another reason I tend not to use comments all that much is that they make code a little harder to follow and understand, just as classic VB, PHP, ASP and LUA scripts in HTML pages made the web page content very difficult to discern, comments do the same thing to code. It's also been my experience that many programmers just don't know when they should be using comments or how to properly use them.

Self Documentation

The biggest push for using comments is usually for the purpose of documenting the objects, methods, properties, algorithms and libraries within an application. While on the surface this seems like a great reason to use comments, the benefit is lost if the comments are not maintained as the code evolves -- and they rarely are maintained. Secondly, documentation is usually verbose and blocks of multi-line comments tend to breakup the logic flow when reading the physical code.

A good programmer should always write code that is geared toward self-documentation. In a nutshell, to accomplish this, variables should be given meaningful names. Be descriptive, not cryptic, in your naming. With Intellisense, writing a 30 character variable isn't a huge task anymore, so there's no excuse not to name a variable descriptively. Objects, methods and properties should also be named in a way that is intuitive to the programmer using them.

// This is poor practice

int test = 0;

int test2 = 0;


// Recommended Practice

int iCount = 0;

int iSubCount = 0;

string sApplicationName = string.Empty();

While we're on the subject, methods and routines should not be so obtuse and long that they become unintelligible. Also, as an application's code base matures, split large functions into smaller ones. There's absolutely no gain in creating monolithic objects, methods and algorithms since they are always harder to maintain and understand.

Intellisense

Today's code editing packages and compilers have become a lot more user friendly to programmers, especially with respect to the .NET framework. Due to .NET Reflection and structured support for meta information, there are a few more tools available to the programmer when it comes to documenting and dealing with getting information to other programmers. The most important of which is Intellisense. Through the use of attaching comment information for methods and their arguments etc, developers making use of your object now actually have the documentation at their fingertips as they invoke a method on your object. I do recommend the use of comments in these cases as the comments are outside of the actual code for the method and they tell a programmer how to use the method in an instant. However, it is important that comments still be kept brief, real documentation should still exist in some other place, whether its in a document file, a web site, a help file or a WIKI. Meta data isn't the place to explain the nitty gritty details of your code.

/// 

/// Takes a string and modifies it so that the string uses all capital characters.
/// 
/// The text string to convert to uppercase characters.
/// Returns the text passed in using only uppercase characters.
public string ToUppercase(string sText)
{
	...
	return sReturn;
}

Regions

One of my favorite non-important but very useful features in Visual Studio (I'm unaware if other editors support this, but I'd guess others like Eclipse probably do by now) is the concept of code 'regions'. Through the use of specifying meta-data regions you can essentially organize common functionality within a larger object or code library as you see fit. I tend to group my private, protected and public methods together in their respective regions, or if I find a group of functions all relate in some way, I'll place them in a region that shows they are associated. The great thing about regions is that in the code, you can hide or show the region as a whole, and this goes a long way to managing larger code files. With a single click, you can simply hide 200 lines of code you're really not concerned with and focus on what you are. My best description of the use of regions is how the use of white space, while seemingly unimportant, has a massive effect on the understanding and management of code, books, advertisements, etc. In the same way, I think regions help the developer focus on the task at hand rather than getting lost and overwhelmed with a screen full of code they shouldn't be concerning themselves with. They are similar to comments that used to be used to group like code, but now you can use regions which don't at all interfere with understanding your code.

#region Private Methods
private void MyFunction()
{
	...
}

...

#endregion

#region Public Methods

public string MyPublicMethod()

{

	...

}

...

#endregion

Programmer Testing

One of the more useful practices involving comments is probably when a programmer is making code changes (bug fixes, feature requests etc) and in the course of implementing the change they will comment out existing code temporarily to test the new code or get a better understanding of the code they are affecting. This is a perfectly sound technique and I would guess one of the first reasons comments were introduced in early languages. However the problem with this is that once the solution is implemented and that code is checked in, usually the commented out lines are still there. Over time, more and more of these commented lines keep showing up, just breaking the flow of the code and making the code look quite ugly and harder to maintain. My advice is to not get in this habit, if you do comment code out temporarily, remember to delete it before checking your changes in and if you are editing a file that has this problem going on, go through and delete the commented out sections. Very often one of the big reasons this stuff shows up is because a developer isn't sure about their change and they want to keep a backup of the original code in case they're change isn't the correct one. If your using a code repository check-in/check-out system, the original code will already be there, there is no need to fragment your code base with temporary but permanent commented out lines.

...
// This is poor practice, it's much smarter to just remove the commented out lines if they aren't being used.

//int i = iCount + y;

  //int i = iCount + y + 1;

//if(iCount > 4)

int i = iCount * y;

...

While I usually don't put a lot of emphasis on the use of comments in code, I think it definitely has its uses in meta-data in conjunction with intellisense as long as its not overused, it should be brief and to the point, almost like a mini-reminder to the developer. Otherwise, extensive uses for comments should be relegated to situations that are very complicated or contain a lot of very specific steps etc. If you feel that you need to use comments to explain the majority of your code, my guess is that you aren't writing your code to be self-documenting and making better use of variable, object, method and properties names would probably be far more beneficial. If you catch yourself commenting out existing changes and can honestly say its because your a little unsure of the changes your making, it's probably a better idea to give yourself some more time to ensure the changes your making are the correct ones, you should be able to comfortable removing original code lines that are not needed before checking in your changes.

These suggestions are from my personal experiences, I've made all of the mistakes put forth here - and many more - and I've found that these suggestions have gone a long way to making my code easier to understand, maintain and pass on to others. In general, I would say that I side with the camp that would recommend you use comments sparingly, except for situations that really, clearly call for them.