When should I add comments to my code? [closed]

Answer 1

When you do something non-trivial, as you're writing it.

Answer 2

Early on in my career I added comments to nearly every line of code, as you may do perhaps in an ASM program. As time went by I ran into many of the problems mentioned here. It was a bear to maintain which resulted in not updating comments and then they become stale at best, usually moldy.

I feel that the # of comments should reflect how complex or non-obvious the code itself is. In a more challenging environment, such as ASM, you will probably need more comments to understand what is going on. In more modern languages like C# you shouldn't need a whole lot of comments in most cases.

Generally I use tools that evaluate the complexity of my methods in C#. Those that are high on the complexity scale first get refactored. Then when I'm satisfied with the complexity remaining and I still have some code that is not obvious, or even more important, seems obvious but does something different, then I tack a comment on it.

Answer 3

The question should be, when do I add code to my comments?

My practice is to write out the functionality of a module/object/function as a series of comments. Not comments like "add one to counter". Higher level comments like "sort list by account number". Detailed comments are pretty much redundant with the code. So I avoid those unless I'm writing a very tricky algorithm. Once I have the functionality "designed" in comments, I act like a human compiler and add in the code after each line of comments.

Give it a try and let us know how it works!

Answer 4

You gave a lot of cases in your question. I think it depends on what you're doing at the time.

If you're writing a function or a class, comments are a way to declare what's supposed to happen with the function. Things like input variables, output type, special behavior, exceptions, etc. IMHO that kind of comment should be written before the actual code is started, in your "code design" phase. Most languages have packages which process those kind of comments into documentation (javadoc, epydoc, POD, etc, so that stuff will be read by users.

If you're making a bit of code work, I think it's OK to wait until you've got it working to put in a comment triumphantly describing your working solution. That kind of comment is only going to get read by a code reviewer.

Then, as others have said, you want to avoid WTF moments, by yourself or others. I once got an attaboy for a comment I made once in an open-source project. The comment was "Yes, I really do want = and not == on that line."

Answer 5

I add comments while writing any code that is not easily understandable. I find that if I don't do it immediately then it gets forgotten. I (or more likely someone else) then spends more time figuring what I did than it would have taken to write the comment.

To be more precise, commenting immediately after the code is written is the best avenue to ensure comments actually get written.

Answer 6

A. when you decide an arbitrary decion that would be difficult to re-understand. B. Every thing that you feel that you should remember while writting the code C. in the beginning of a program explain the logic and use Advice - instead of commenting a lot use long names for functions and vars that realy explain what the function does or what the variable stands for.