Question

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

Answer 1

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.