Should we write comments extensively?

Question

Possible Duplicate:
Commenting code

C# is high level language and these days I have come across code which has less comments as compared to code written a few years ago. Should we really comment a code to great extent? Just want to know thoughts from you people.

Answer 1

I live by 1 rule; dont comment obvious code.

I also try write code as obvious as possible, hence a huge lack of comments in my code :)

Answer 2

From the older days of computing, don't comment everything, for instance:

if(a == 3) { // if a equals three, then...
    cout << "a is three" << endl; // output "a is three" and a newline
} // otherwise don't print anything

a++; // increment a

Comments should make sense above all. It is good practice to provide a comment header on each function, or class, but don't comment every single line.

Answer 3

It is not necessarily quantity of comments you want, but quality. Comments should add understanding to the code.

Answer 4

C# have both an imperative coding style (for(each), while etc.) and a declarative style (LINQ, queries).

The declarative style is a lot more readable and needs fewer comments in my opinion. Everybody can see what this code do:

var males = from person in persons
            where person.Gender == Gender.Male
            select person;

But with a for(each) loop version it may not be that visible (for something more advanced maybe) and comments is needed.

=

Comment when the code is'nt clear for others (and you).

Answer 5

My suggestion is to write comments in a useful schema, such that the comments are readable by documentation-generating programs like Doxygen. This will reduce a lot of time to write documentation.

Answer 6

1.) write code that must not be commented

2.) if you really need a comment this is often a code smell - maybe you can change something and you must not comment it

Answer 7

There's an entire chapter dedicated to comments in Robert C Martin's excellent book Clean Code.

A few highlights:

• Prefer refactoring over commenting
• Don't comment the obvious
• Keep types and methods short and focused (SRP)

Answer 8

I agree with this:

http://www.codinghorror.com/blog/2008/07/coding-without-comments.html

Answer 9

self-explaining variables and method names are much more important than comments. If the names are good and the architecture is simple to understand, almost no comments are needed.

So only comment method headers and parameters (for auto-generating the documentation) and within the implementation only if it is a complicated algorithm or design pattern (sometimes a link to a paper or Wikipedia is sufficient) or a "hack" or workaround.

These complicated and "dirty" parts of code is what I try to comment very extensively, because these are the parts of code where others (or you after 6 months) only think "WTF?", when seeing the code - so explain why you have done this and what must be done to improve the code. (Often you know this when implementing a hack, but theres too less time or risk (and thus testing-effort) is to high).

Answer 10

Put comments that may or may not seem to be a straightforward approach. This means to add comments to say what algorithm you are using (say, during a sorting method, you may want to mention if your using Bubble Sort or Merge sort), or in cases where your making changes to the original algorithm (ie. splitting an unsorted list into groups of three, instead of two, when doing Merge Sort).

Basically, if someone else looking at your code can be confused and is a somewhat competent programmer, throw in a comment to explain what you are doing and why.

Answer 11

One argument for extensive commenting is that when we program, we all have different styles and methods. Where I work, two or three of us could be sharing the same project and if I've been hacking away for week and I hand it over, they wouldn't have a clue where I'm coming from.

I tend to comment when I have something to explain to the person using the code. They know how to program else they wouldn't be looking at code.

//check to see if variable is X
if ($variable == "x"){
    return true;
}else{
    return false;
}

I wouldn't go overboard with these comment but if I think I have something to explain, then I do so

Answer 12

Write comments that explain why you are doing something, not how you are doing it. The code should be clear enough for others to understand the how.

Answer 13

Yes, comments are very useful, not just for you but also for others.