Code documentation is important, but it is sometimes very painful for a variety of reasons. For example: It is not updated as often as the code. It is harder to maintain than the code because it describes how something is achieved in too great a detail. It often describes functionality that is not actually under the control of the code.

One of the worst problems with code documentation is that it often describes how something is done rather than why.

Describing why code exists is easy: Refer to requirements in the code. For example, if a function fulfills a requirement directly then add its requirement number to its header comment. Citing requirements in code facilitates quick solutions to these common problems:

1. Developers know why each class or function exists and what it is meant to do; one word/number represents an entire concept/statement.
2. When tests indicate that a specific requirement is not properly fulfilled, a quick search of the code will reveal where the problem is likely to originate.
3. When a requirement is modified after it was implemented, a quick search of the code will reveal where code modifications need to be considered.
4. When coverage tests reveal dead code, an inspection of the comments may reveal which set of tests need to be updated. Conversely, it may reveal that the code was designed to fulfill a requirement that is no longer supported.

Requirement text can also be useful when added to code comments. When you describe a piece of code, that description is very likely to contain a restatement of the requirement text.

Some argue that this practice will too-often result in comment-only edits to source code files. This will only happen if your SDLC process permits requirements to be changed mid-project without proper consideration of their impact. It should not happen in an organization that treats requirements changes with proper reverence.

Requirements should only be cited in code that directly implements them, and any change to a requirement should impact that code, so comment-only edits to source code files should be a rarity.