How to avoid falling into the trap of not commenting code?

Question

I've been working on a project for about a month now. I am extremely familiar with the code and understand it to the extent where I feel that it is so easy to understand, that most methods don't need comments in my opinion. I can't tell if it's because it is actually simple code or that I am just very well practice on how it runs. How do you draw the line between simple code and code that needs comments?

Answer 1

If the code is simple it should be easy to comnent. Just do it, in full gramnatically correct sentences, using consistent snd appropriate nomenclature.

On some occaissions you may find it hard after all to write a good documentation header or you will find a method that does more than it should.

Taking documenting seriously leads to better code. It strengthens your design by forcing you to express your logic in a different language. If the design still makes sense when you are done you should be good. If it starts feeling wrong or you are having a hard time coming up with a clear description, you still have some work to do.

And last but not least, it will make your code more accessible, if not to someone else to yourself after you forgot what it did.

If you write in C#.NET, check out StyleCop. I like that. But there should be something similar for any language.

Answer 2

I'm in the same situation. After working on code for a while, you become extremely familiar with it. You know how it works. But imagine if you were to read something that someone else wrote for the first time. Comments would make that code a heck of lot easier to read. What I generally like to do (and I have very limited experience) is to make a higher level comment for algorithms and functions that explains what they are generally doing. And then if there is a line of code that does something more complex, like some kind of calculation or something, then include a comment explaining what is going on. Hope this helps.

Answer 3

Simple. always comment and put an auto mated check which prevents code with no comments being checked in.

Advanced programmers might start skipping comments which are the same as a function or variable name.