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

Answer 1

This is subjective, but sometimes it's better to add them before the actual code, eg. when you implement an algorithm that has clearly defined steps. By that way it's harder to miss steps.

Answer 2

This is a matter of style. Personally, I like writing comments during the coding, not after. Because it I leave it to after, I usually get lazy and don't write them at all. That said, sometimes it's useful to go over a completed piece of code, figure out what isn't obvious from the code itself and document it. In particular, the parts where assumptions are made.

Answer 3

The short answer

The short answer is anytime something is non-obvious relative to whose going to be reading it. If its code that is still in flux so you are the only consumer, just comments for you (hours and days). Ready to check in for others to try out - comments for you and your team (days and weeks, possibly months). Ready for wide release - comments for the immediate and future public (months and years). You have to think of comments as tools, not documentation.

The long answer:

• When I'm writing it? - Yes
• After I got a part done (Single class/function/if-elses)? - Yes
• After I got the whole thing working? - Yes

When I'm writing it? - Yes

Drop comments anytime you hit a place where the code isn't immediately clear. For example, describe the class when the class name isn't clear or could be interpreted too widely. Another example is if I'm about to write a non-obvious code block, I'll first add a comment reminding me of what I want/need. Or if I just added some code and I immediately realized there was a gotcha in there, drop a comment to remind yourself. These comments are implementor comments, less to help future maintainers, but rather to help yourself in the coding process.

Drop FIXME - explanation and TODO explanations reminders as you go.

Code is still in flux, so I'm not yet documenting every and all method and parameter.

After I got a part done (Single class/function/if-elses)? - Yes

When I'm reasonably done with a method or class, now is the time to review it. Along with checking scopes of methods, ordering methods, and other code cleanup to improve understandability, now's the time to begin to standardize it against your team standards. Consider what comments are need based on the audience it will be released to (future you is part of the audience too!) Does the class have a header block? Are there non-obvious conditions under which this method should not be called? Does this parameter have any conditions on it, e.g. should not be null?

Check the FIXME and TODO items - still valid? Any you should address now before moving on?

These are still notes for you and your team, but the beginnings of standardized notes for future maintainers.

After I got the whole thing working? - Yes

Now is the time to review everything and finalize comments against your standards.

All FIXME and TODO items addressed (fixed or captured as known issue)?

These notes now are for future maintainers.

Now the dirty little secret

More is not always better. Like unit tests, you have to balance use of your tools weighing costs vs benefits. The fact is that a coder can only type so many physical lines per hour - what percent should be comments? A low percentage means I've got a lot of code, but its confusing and difficult to understand and use correctly. A high percentage means that, in an hour when someone changes a method signature or redefines an interface, all the time is spent fully commenting every parameters of those methods just got trashed.

Find the right percentage based on the stability of the code, how long it will live, and how widely it will be released. Not stable yet - minimal comments to help you and your team. Stable and ready for project - fully commented. Public release? - fully commented (check again!) with copyrights (if applicable). As you gain experience, adjust the percentage.

Answer 4

Before you forget what specification and design the code is required to implement. Before you forget that some unfortunate coder will have to read it later on. Before you forget that the unfortunate coder could well be you.

Answer 5

You should never "add" comments - they are not additions. Comments are part of the code - you use them when you need them. Asking when you should add them is like asking when you should add functions or classes. Though thinking about it, I remember doing a program advice slot at university I worked for where one of the students came in with about 1000 lines of Pascal, with no functions. When I queried why he hadn't used functions, his response was "I'll add them later, once I've got it working."

Answer 6

A disadvantage of adding comments later is that a lot of times that will simply not be done, due to lazyness, other tasks, etc.

If you find you can always go back and add the appropriate comments without any problem, then by all means do so, but otherwise making a conscious effort to add them as you're coding or before you code a section may be a way to ensure that you don't leave the code uncommented.