Importance of commenting your code

Question

How do you explain your team mates the importance of commenting the code they write? I know some coders who write episodic comments while others leave a lot to be expected, what do you expect when you read comments?

Answer 1

if the language you are writing in is not human readable, i suggest very granular method and procedure level comments.

if the language you are writing is human readable (C#, VB, etc..) i suggest that you use somewhat detailed comments at the method level and minimal comments at the procedure level.

Answer 2

There are some minimums:

1. All functions and classes should be commented
2. Try/Catch and exception handling is better to be commented
3. Constants hard coded in the code should be definitely
4. dummy objects and dummy classes, as well as TO-DO parts should be commented
5. When you get a code from a URL, the address should be cited in the comments for further consideration and copyright infringement problems
6. Also commits to the version control system should be well commented

Although comments should be kept to minimum, there is no need to comment a for loop definition when it is obvious, I usually set ground rules for my programmers, they stick to it when it is well defined

Answer 3

Write comments when you're writing code that's not intuitive. There's really no reason for commenting a method that just iterates an array, but when you fix a bug or have to hack something together to get around an issue, it's good to have a comment so you can quickly understand that code 6 months later (and not accidently undo it).

Answer 4

What do you mean by commenting code? The actual code, or the function headers?

If you're actually talking about the code, it's a lost cause. You need to get them to write readable code and to break it into meaningful chunks. Commenting bad code doesn't make it into good code, it just leaves an inconsistent mess.

As for header documentation, you have to get them to capture the important things (e.g., surprises, directives) and compromise about trivial things (listing all parameters, repeating what the signature does). People hate documenting functions because most of the effort is spent writing trivial text that almost insults your intelligence (e.g., on getHandleToFile(), "this gets a handle to the file"). Since there are actually a lot less important details than one would expect, they'd be pleasantly surprised and would be more likely to invest the effort in those specific situations.

Answer 5

• Include comments for document generation on methods and classes.
• Don't comment every line.
• If you are doing something expected or that is not obvious from the code, explain why in comments.

Answer 6

I think if you are writing code that others may someday have to follow, then it is prudent to leave good comments about what things are doing. If you are just writing something for yourself, the tendency is strong to leave minimal or none at all. That being said, I have had the "not so luxury" of having to go back to code I wrote 8 years ago and didn't comment adequately, in a language I don't use anymore (class ASP) and I can tell you, I wish I had left more comments!

Answer 7

The most important thing to do in commenting is to tell the truth. The number of times I've been investigating a bug only to find a section of code that is "less than obvious" along with a comment that says it's supposed to do the opposite to what it is doing. Who wins? You decide...

On a related note, any comment that is longer than the section it is documenting is normally too long.

Answer 8

The best comments are always concise, in a few words. It should say what's not obvious in the code. I see allot of people making obvious and therefore useless comments like:

if x==0 //if x equals 0 then...

oh really?! This is only "polluting" the code, because unless you're learning how to program, its pretty useless.

Even if the code is only yours, you should write comments as if you were about to share it with another programmer that is completely unaware of it. That way you make sure that you will always understand it, and in long term if somebody comes along and picks that code up, that person will be able to understand it and extend/use it.

I see comments as a boost of reusability. And I expect, like every other programmer, to fully understand a block of code with a single, simple and concise comment.

Answer 9

I try to comment most of my public methods and classes, and in those comments you can read what the method does, what the meaning of the parameters is, and, if applicable, what the output will be.

I also sometimes put comments inside my methods, but, there I do not comment what I'm doing, but why I am doing it like that.