Ask any programmer what the most irritating part of programming is, and they’ll either say “debugging” or “documentation”. Admittedly, I am one of the rare exceptions (I dislike the “coding” part most, because it’s less about solving a problem than it is translating the solution), but I have a standard which removes the most irritating factors of documentation.
The Classic Method
During the programming phase, code authors sit together and draft up diagrams and flowcharts for how their code should function. They then sit down at their machines and, over a course of weeks and countless modifications, produce some quality code.
After they’re done writing the code, they go off to do more coding. Because they’re programmers, this is their natural state.
At some point, however, they have to sit down and create documentation which details the operations of their functions, the code’s basic assumptions, and requirements on the end-users.
The thing is, at this point, even the authors don’t remember what the code does, or what the assumptions are. Even if they are documenting the code right after cleaning it up, there are functions whose purposes are now essentially erased from memory.
This means that the authors have to sit down, re-read their code, figure out the assumptions and operations again, and remember what the requirements are.
What a long, boring waste of a programmer’s time.
Documenting as you go
First, we have to remember a vital documentation rule: Everything which is related to the code is documentation. All your comments, graphs, doodles, and idle musings are valuable insights into the mind of the programmer which constructed this code (as opposed to the programmer who is currently reading the code).
I highly recommend that, as you write your code, you place useful comments and tags in there. Something as simple as “This block is full of variables we need for this operation” can save you minutes of inquiry, while longer comments detailing the flowchart for a function (or subfunction) can save you hours. Also, if you use meaningful naming conventions and meaningful cross-referencing, you can skip around your code in seconds, connecting the spaghetti into a single whole.
Of greatest importance to the end-user, always document your function’s purpose, return types, and arguments before you even start fleshing out the details. This will spare you confusion (as you never let the complexity of the function spiral beyond the defined purpose), and it will allow you to create your final documentation almost effortlessly.
Naturally, if you make fundamental changes to a function, you have to update your documentation. It may still be worth leaving some of the old code commented out, just so you have evidence of a useful pattern or idea.
I am a tremendous fan of the doxygen program. This program interprets declarations and specially-formatted comments to generate HTML documentation, complete with hyperlinks, graphs, and flow-charts. With this tool, you can rapidly convert useful source-code commentary into powerful documentation.
The format is extremely minimal. All comments surrounded by /** … **/ blocks are interpreted by Doxygen, along with all in-line comments starting with ///. This means that a single-character addition in a regular comment results in a doxygen comment.
The tag system in doxygen is also simple. Every line beginning with a particular tag will produce a section of meaningful output in the final documentation. These tags include (but are not limited to):
- @param – Describes a function input parameter
- @param[in] – Declares the parameter to be input only
- @param[out] – Declares the parameter to be output only
- @param[inout] – Declares that the parameter is read in, transformed, and passed back out
- @return – Describes the expected return value(s)
- @author – Lists a name as the author of a file, function, etc.
- @brief – Declares that the line which follows is a brief description of the function
- @detail – Declares that everything up to the next tag is part of a detailed function description
We also can use ///< to describe enumerations, objects within a structure, etc.
It is a tremendously powerful tool which encourages ample in-source commentary and provides rapid documentation on demand. For more information, check out the Doxygen user’s manual.