Program comprehension is the ability of a programmer to understand what a computer program's source code does. In computer science instruction, comprehension of a program is frequently overlooked in favor of learning the mechanics and syntax of the computer language being taught. Writing comprehensible code, however, is a universal need, regardless of the computer language in which it is written. If a programmer writes a library or piece of code, but no one can determine what it does afterward, the algorithm and logic behind that code can easily be lost. It is increasingly common that programmers cannot decipher their own code, since it often isn't written clearly and intuitively.
There are two main strategies programmers can use to improve program comprehension, and each has its own advantages and drawbacks. The first method is to add documentation to code during or after code creation, and the second is to write code with an emphasis on its structure. A combination of both approaches is helpful to most programmers, although there are some code builders who prefer one strategy over another. Which method to use is a matter of personal preference by the programmer, and any attempt to clarify code is far better than none at all.
Adding documentation to code is the simpler of the two methods, and when done well it can be a very useful crutch to a programmer unfamiliar with the language the code is written in. Most computer languages have a specific documentation style to aid in program comprehension. If code documentation is written thoroughly, a new programmer's first step can be to read all the documentation and comments to gain an understanding of how the program works, without having read the code at all. Instead of being dependent on the code syntax and mechanics, the programmer can see what is happening in plain text, then relate the text to precisely what is happening at any given place. When adding documentation to code, however, programmers must be cautious, because too much documentation can be confusing and intrusive, rather than helpful.
When writing code with an emphasis on structure, a programmer assumes that any other maintainers looking at his or her code will have an equivalent knowledge of the language's syntax and mechanics. Sometimes, this is a valid assumption, but it cannot always be relied upon. Program comprehension based largely on structure is possible, but it takes significantly more work on the part of the original programmer to facilitate it. The mechanics and syntax of the language must be followed exactly, as well as all stylistic conventions, and everything must be consistent. When writing code this way, a programmer must always be conscious that what is clear to him may not be clear to another person.
Even when writing code with an eye for later program comprehension, additional documentation or structural modifications may be needed later. This is a natural part of code maintenance, and not a failure at the hands of the programmer. A programmer's job is to anticipate as many comprehension problems as possible, but all of them are not always caught.
