Reading Is Learning

Reading as learning
Developers and maintainers read the API documentation and the source code in order to learn something new, or well-forgotten old. Reading is learning. When you have enough knowledge to complete the task, you stop reading and start writing.

Elements
Learning starts with simplest, easiest, recognizable, and memorable things. When you are learning, begin from the basics, like object's lifetime control (opening/closing, construction/destruction). When you teach the reader of your code, begin with well-known, trivial operators of C++ language, variables of fundamental types, plain function calls, and non-template classes.

Glossary
In order to understand the problem area, the human being needs to know the language of that problem area - specific words that define essential things and actions. Definitions of problem-oriented terms should be used consistently. Well-chosen term describes only one entity. When you read or write the code, watch out aliases - different names for one object or process. Watch out homonyms - cases where one name used for different objects or processes. The worst case is a term with a variable meaning applied to group of unrelated objects - in fact, it does not have any meaning.

Examples
The easy way to clarify the definition is to give an example. The shorter the distance between the definition and example is, the better the understanding is. Good examples do not contain irrelevant details.

Sequence
The order, in which new definitions are appearing and using, does matter. The reader easily understands new terms, if they are based on already well-known terms. Forward definitions ("I'll explain it in details next week, just be patient") require extra motivation of the reader, so avoid using them.

Reminders
Good teacher helps the students to memorize the course and reminds them already explained stuff. Often you should repeat the part of the lesson, or else the auditory will forget everything.