From basic beginners to experienced experts, everyone is either a poor commenter or knows someone who is a poor commenter. If you need a hair cut, try understanding an open source uncommented project. You will tear out all of your hair from frustration.
Not writing comments is bad, but so is writing bad comments. If your comment is so vague that if I'm reading through your code and it seems completely random, or makes me have to remind myself what kind of project that I'm looking at, maybe it shouldn't be there.
There are 5 types of comments that I've seen:
- No comment - There's nothing there (Bad)
- Vague comment - It just doesn't make sense in the context (Bad)
- //This counts
- Unnecessary comment - It just doesn't need to be there (Bad)
- //this line adds 1 and 2 together
- Funny comment
- Helpful/Descriptive comment - Brief yet descriptive about the method/function. Placed at a point in the program that could be potentially confusing. A helpful comment might also describe how the function or line works(Good)
- //This flag is true if the VM is halted
In addition, there are multi-line and single line comments. Just think "Evaluation vs. Explanation" To put it simply, Use multi-line comments before functions do describe those functions and use single line comments to describe a complex line.
So just be aware of these things when writing comments and try to think of the other programmers, or even future you who will be reading this code in the future and will not know the ins and outs of it. When writing a program, it is very easy to slip into the focused mindset of writing code and being aware of where every function is, what file is in, and how it works. This is fine however, when you come back to it with fresh eyes, it will be hard to know where to begin (trust me! I've done this so many times).