The Craft Of Coding

CPP 25-Apr Documentation

Posted by Pete Sun, 24 Apr 2016 22:27:00 GMT

Just when you thought you had finished the program, the awkward question is asked

Do you understand how the program works?

Many different types of documentation

  1. Reminders to yourself while writing the program — these do not have to be permanent, since once that part of the program is finished, the notes are no longer needed.
  2. Design ideas about how you plan on building the program — sometimes you need to keep these, other times they can be thrown away.
  3. Notes to users on how the program works — also known as user documentation. This is a key deliverable if you are writing software for others to use. Some companies go as far as writing the user documentation before they write the program.
  4. Maintenance notes for other programmers on how to maintain and extend the program — As a minimum this needs to describe the major constructs used in the program and how they are interlinked to deliver the functionality. Some people go as far as naming and describing what is in each file in the project.
  5. Dependency management — recording the things that the program depends on in order to be built and to run. At the most basic level you need to know what version of the compiler and operating system that were used to build the program, and the target operating system that you intend the program to be able to run on.
  6. Design documentation — explaining the as-built design of the program, as distinct from the intended design of the program.
  7. Tests and test results — explaining how the program was tested and the test cases that were used. This is very important when a defect is found, since the test cases will show the causes of the fault that can be ignored (assuming that the test cases pass).
  8. In code comments — explaining the more obscure parts of the code, when it is not trivial to rewrite the code to make it clearer.
  9. File header comments — explaining what is in the file, and what should not be in the file.
  10. Intention revealing names — when naming methods make sure that the name gives at least a hint of what the method does for the caller, the name should not indicate how the method actually works.
  11. Classes name concepts — so whenever naming a class, remember that you are documenting the important concepts in the program.
  12. Requirements — remembering why the various restrictions on the program exist is key to being able to extend the program in the future.

To Do

Document your program, taking into account the above concepts. To help you guide your documentation, make sure that it explains what you would have to do to add ^ as the power operator. The result of 2 ^ 2 should be 4.

© Pete McBreen 2016 Let grammar, punctuation, and spelling into your life! Even the most energetic and wonderful mess has to be turned into sentences. — Terry Pratchett