4. Source-Code Documentation

Source-code documentation is conveying to a reader (another programmer, or to yourself in 2 years) what the designer/programmer was doing and thinking when the software was written. In writing and documenting code, it is important to remember — to roughly quote one of the great fathers of Computer Science, Donald Knuth — that when you are writing source code, you are not just teaching the computer what to do, but also teaching other programmers how it works, not only users of the API, but also future maintainers of your source code. Comments add information about what the author was thinking when the code was written, and why you did things that way — subtleties about the design that cannot be conveyed by the source code alone.

In that last concept — subtleties about the design that cannot be conveyed by the source code alone — is the need to present a design overview of the subsystem contained therein, and answer The Basic Questions about JUST that subsystem at the top of the main source-code file for that subsystem. In some libraries (such as my own), this documentation is found where the source code is. There are good reasons for this, and they are well-explained in the Articles on Documentation-Driven Development.

Some other libraries may prefer having that documentation in the .H files, which can be the case where the library may be exported as a binary file (linkable or dynamically loaded).

TODO