Practices - Comments

Comments are encouraged for:

• difficult code – ie one that has no apparent sense in its context

• code that, for some reason, breaches of the coding standard

• code that comes as a legacy.

Comments should not describe program logic flow.

Comments should describe rationales behind the commented code.

For regular code use the identifiers which describe what they are. For example, class which holds a collection of definitions of content which are trees which use seasonal changes shader can be called:

seasonal_tree_definition_content_provider;

Names from 3 to 6 words are preferred.

Rationale: keeping comments in sync with code they comment is doubling amount of work, exposing the risk of comments providing false information.

Note: comments should be considered the same thing as annotations are in a book. They might help, but a book written entirely of annotations is difficult to follow.