5 - Documentation Conventions

Summary

Developers often forget that the primary purpose of their software is to satisfy the needs of an end user; they often concentrate on the solution but fail to instruct others on the use of that solution.

Good software documentation not only tells others how to use your software, it also acts as a specification of interfaces and behaviors for the engineers who must help you develop the software and those who will later maintain and enhance it. While you should always make every attempt to write software that is self-explanatory, your end users may not have access to the source code; there will always be significant information about usage and behavior that a programming language cannot express.

Good programmers enjoy writing documentation. Like elegant design and implementation, good documentation is a sign of a professional programmer.

Document Your Software Interface for Those Who Must Use It

Document the public interface of your code so others can understand and use it correctly and effectively.

The primary purpose for documentation comments is to define a programming contract between a client and a supplier of a service. The documentation associated with a method should describe all aspects of behavior on which a caller of that method can rely and should not attempt to describe implementation details.

Describe each C++ element that appears in, or forms part of, the interface.

Document Your Implementation for Those Who Must Maintain It

Document the implementation of your code so others can maintain and enhance it.