Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I've used some older languages before C# and I always felt the need to comment what I was doing so it is clear for anyone who reads the code.

But now that I use C# decently, I often feel that it's a pain to write most of the comments because I feel like I state the obvious. So unless I do complicated formulas or algorithms, I'm not sure how I should comment. Microsoft has reached such a readability in C#, I'm mesmerized.

Do you have the same feeling? How do you write your comments so they are not pure redonduncy? Have you changed your commenting habbits / best practice?

share|improve this question

migrated from stackoverflow.com Apr 2 '11 at 13:12

This question came from our site for professional and enthusiast programmers.

1  
The question is not entirely the same, but the answers are very similar to the answers on this other question: stackoverflow.com/questions/121945/… –  Protron Apr 2 '11 at 1:13
2  
I use XML documentation "comments" extensively in C#. I think it's made most in-line comments obsolete, except, as you mention, in very specific and obvious cases. –  Cody Gray Apr 2 '11 at 13:15
1  
Consider strongly if you document "WHY" instead of "HOW". The WHY should not be obvious. –  user1249 Jun 9 '12 at 15:47
add comment

7 Answers 7

up vote 5 down vote accepted

There's no point in commenting the obvious.

Things you want to comment:

  • the intention behind your code;
  • any references that may be useful to the reader;
  • any assumptions or important invariants;
  • any clever tricks you've used.

Basically, your code is telling a machine what to do; your comments should tell the reader what you intend the code to mean.

Whatever is the appropriate amount depends on the context. Grab the coder next to you and show them your work. If they can't work it out in around five minutes, you haven't put in adequate documentation.

share|improve this answer
    
I find it helpful to use asserts for assumptions and important invariants. Clever tricks should always be kept to an absolute minimum. –  dan_waterworth Apr 2 '11 at 19:13
add comment

I abide by the rule that the code itself explains what is happening, and the comments are there to explain why I'm doing it this way.

I write comments as if I'm speaking to an audience of other C# developers that are making an effort to understand what is going on, or to myself after I've forgotten about the project and I come back to it. I wouldn't want to read boring obvious statements that repeat what the code tells me. I'd want to see why this approach was taken, or gain some insight into what the developer was thinking, etc.

Of course, in certain complicated blocks of code, a good comment explaining what is happening is still appropriate.

Whether that adds up to 1% or 20% is irrelevant as long as the comments are useful.

share|improve this answer
add comment

I don't know that you need to quantify it like that.... My feeling on comments is to put them where someone else that's viewing my code would want to understand something that's going on. I tend to put a lot of comments into my code, but where it makes sense to do so. I don't think that you can say 10% or 20%, it's not how much, but how useful.

share|improve this answer
add comment

The task you need to do with comments is to tell future readers WHY you do things as you do. The HOW is told by the actual code, but there is a limit to what you can say.

For instance, good candidates to comments are WHY you chose to implement a specific sort routine instead of just using the one in the runtime library. You might know that the swap-element routine is very, very slow (perhaps because it works directly on storage media) so you have chosen an algoritm that reads all elements, figure out where they go, and swap each of them exactly once into their right location, perhaps even in the right order to minimize disk access. This is important information and future maintainers need to know. A comment - even a small one - will tell them that there is a good reason for it being like that.

This implies that the more telling your code can be - which is one of the benefits of refactoring - the less commenting you need to do. This again mean that the amount of commenting depends on the code, so absolute numbers cannot be given.

My rule of thumb is "What would I really like to know when looking at this code in a year or two?" and then put that in. Plus some more.

share|improve this answer
add comment

If a comment is redundant, it's not worth writing.

C# allows the developer to write code that explains itself. Almost every time I write code that needs to be thoroughly commented and invest a lot of time commenting it, two hours later I find myself refactoring the whole thing out and replacing it with a better self-explanatory solution.

I don't know about 10%. When I was developing for a critical system in C, comments took up 30-50% of the code. In C# I usually only comment the methods (only if their name does not entirely imply what they do) and algorithms. And if the methods are short (less than 10 lines), you may say that comments do take up 10% of the code.

share|improve this answer
add comment

I try to write code clear enough that inline comments are usually not needed. Anyway I keep my methods short and use a docstring, and that is enough to keep my comments/code rate well above 10% (I would say they are about the same length).

share|improve this answer
add comment

If you mean in line comments then the answer is "it depends"... It depends on what the code is doing and how complex it or non-intuitive it is. Also, if for some reason you are writing code that would appear to be odd, for example to work around a bug in another system or to comply with an obscure API then you should comment.

The answer does not really depend on your language or platform, you can write readable code in most languages (perhaps not all:-) -- link may be NSFW!) but there will still be situations where commenting is appropriate.

However, this has no bearing on documentation comments on classes and public methods. In my view these are always needed unless you have a masochistic desire to write API documentation in a separate doc. These comments should be enough to explain the functionality of your code to any clients of your API or maintainers of yor code, and in the case of C# they can be easily extraced to produce docs.

By the way, where did you get your 10% figure from? I am not familair with that number.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.