comments?

Megidolaon

What kind of comments do you add and when? I'm sometimes wondering if my commenting is sufficient and other times if it's redundant. For example when I use the same command several times, or when having a loop that only consists of like 3 short commands in total, I feel like I should add a comment, but when I do I feel like it's redundant. I think a comment is redundant if you can easily grasp the purpose of a section of code in 5 seconds or less. If it gets large, comments should only be used for categorizing/grouping. What do you think?

Luc Pattyn

Hi, ahead of a class/method: its purpose and contract, so you know what the class/method represents/does without reading its code upfront in a method: a macroscopic how (algorithm name, reference) and why (e.g. why a particular way was chosen when there are obvious alternatives, and/or why some alternative was not chosen). inside a method: hardly any, it should be obvious, mainly by choosing all identifiers carefully, and by keeping method length limited to 50 lines. :)

Luc Pattyn [Forum Guidelines] [Why QA sucks] [My Articles]

Prolific encyclopedia fixture proof-reader browser patron addict?
We all depend on the beast below.

AspDotNetDev

I usually clump things into logical groups, then I toss some comment above that group of code. If it's a simple bit of code, I use a small comment... if it's more complex, I might use a bigger comment. All my methods have comments on them (though some disagree with this practice and only comment public methods). I comment so others will be able to understand the code easily if they come across it later. I also have various practices for how I comment that I've just adopted over time. For example, I typically shove most of the variables at the top of the method and comment that section with:

// Variables.
int x;
Person person;

It's standard for me, so I know when I see that that I can pretty much skip over that section of code. That illustrates another point -- that comments aren't always to describe the code, but have other purposes. In this case, the other purpose is so I know what code to skip over, which speeds up reading the code. For a similar reason, I comment every single property I have. I do this because it avoids an interruption in reading the code... the consistency between each property means there is one less thing my brain has to process when scanning code. Also, most of the time, you should avoid commenting what the code does and instead comment what the code was made to do. For example, this would be a bad comment:

// Iterates over a list of people and processes each in succession.
foreach(Person p in this.GetPeople())
{
if(p.Height > Person.AverageHeight)
{
tallPeople.Add(p);
}
else if(p.Height == Person.AverageHeight)
{
averagePeople.Add(p);
}
else
{
shortPeople.Add(p);
}
}

A better comment might be:

// Categorize people by their height.
foreach(Person p in this.GetPeople())
{
if(p.Height > Person.AverageHeight)
{
tallPeople.Add(p);
}
else if(p.Height == Person.AverageHeight)
{
averagePeople.Add(p);
}
else
{
shortPeople.Add(p);
}
}

There are other nuances when it comes to commenting code, but you'll develop an intuition for these types of things as time goes on. Whatever system you develop, just follow it consistently.

[Forum Guidelines]

hammerstein05

I think a few developers assume that someone with no knowledge of the language is going to be reading the code. My thought on that is that you should assume that the person reading your code is capable of doing your job and therefore can be expected to understand non business specific rules. As for anything that is really specific to the business, I totally agree with Luc that you should comment a methods purpose and if a specific method has been chosen, why that method was chosen. Future developers may after all think they know better, tear out your code and break any tests, or worse, live environments. As for the code itself, well written code using appropriate variable naming and sparing comments on only the most complex of routines should see you through.

Gregory Gadow

The purpose of comments is to document your code, both for your own memory and to guide anyone who might inherit your work. Sometimes this takes a few words, sometimes it takes a novelette. And just because something is obvious to you now doesn't mean it will be obvious when you come back to it three years latter (experience speaks. X| ) For ad hoc apps that will be used once or twice and discarded, I don't usually bother with comments unless I'm doing something complicated. Otherwise, I will use XML comments on classes, properties and methods, then break up sections of code and place comments at the header to explain what I am doing in that section.

Abhinav S

IMO, a comment should be such that when another programmer picks up your code, he should be able to know what that code does by going through these comments.

Megidolaon

Thanks for the feedback. I was a bit lost because I used quite similar commenting as aspdotnetdev, but recently I finished a C++ class and the teacher complained all the time about me not commenting enough. When I say obvious I don't mean obvious in the context, I mean something like

//checking if strings are ints
for (int i = 0; i < stringArray.Length; i++)
{
bool test = int.TryParse(stringArray[i], out testint)
}

I.e. using blatantly obvious methods and basically re-stating their names (said teacher complained about me not doing that). I tend to group larger sections together with regions, like button events, private methods, etc.

Alan Balkany

In addition to what the other posters said, it's also helpful to have comments explain dependencies/interactions between the code you're looking at, and other code in distant parts of your application. If someone else is going to be maintaining your code, it's these non-obvious interactions that are going to cause them the most problems.