Cure

---

Unless you are abnormally lucky, you will encounter reams of old code that is not properly documented in your career. Much of this code is useful despite the lack of proper documentation. However, this code will continue to prove enigmatic to each new programmer if you do not take the necessary steps to document it.

Analyze

The first step to documenting undocumented code is to determine what documentation is missing. The most important documentation to provide is interface documentation. This is necessary for other programmers to understand the conventions for calling the foreign code. Other helpful documentation is good but not nearly as important. There are automated tools that can be used to assist in this process, but often the documentation is missing altogether and easy to spot even without automated assistance. Other documentation errors are harder to spot without automated assistance, so if you have access to automated checking it should be used. For example, a single argument missing from the documentation of a function with six arguments would only be spotted on a complete reading of that documentation along with examining the function declaration.

Incorrect documentation is different from missing documentation. This is difficult to detect automatically and can often only be determined through the course of using the functionality. Therefore, it is not possible to analyze the code initially to find this form of missing documentation. When it is encountered during development, the documentation should be updated as soon as possible to reflect the correct use and result of the functionality. The one positive aspect of this problem, however, is that the functionality is in use and therefore it is more readily apparent what it does.

Query

Never hesitate to ask the original developer of the code for information to help document that code. This can often be the best source of information you will find for explaining undocumented code. However, this is a fallible source of information, as the programmer’s memory might fail. To reduce the chance of getting incorrect information, you should collect available information about the code so you can ask directed questions. More focused questions will help narrow the search range and jog the programmer’s memory. Be cautious to always ask a question without providing an answer or suggestion to prevent filling a memory gap with a falsely created memory from your suggestion.

Refactoring

There are two important relations between documentation and refactoring. First, consider the refactoring of older code that you did not write. As you refactor, you will gain a better understanding of the code. This gives you the information necessary to fill in missing documentation. This documentation will preserve the work that you put into learning what the code was doing for safe refactoring. Show discipline and write the documentation as soon as you discover what is happening in the code. This will preserve the most accurate understanding of the code without the possibility of memory errors.

The second and perhaps more important consideration when refactoring is to properly update the comments associated with the code that is being refactored. Actually, it should work both ways. Before refactoring, read the documentation that is associated with the code that is to be refactored. With this knowledge, you can ensure that the refactoring will not affect the code that uses the functionality as long as they only require the function to meet its documented specifications. This is a reasonable assumption since the internal implementation should never be used as an indicator of future functionality. If the behavior must be modified to meet new requirements or fix a bug, be sure to change the documentation once the changes have been made. You must also be sure that the documentation of any usages is up to date, and follow this to the first unaffected location in the call hierarchy. This is not a lot of extra work, as you must follow this call hierarchy anyway while doing the refactoring.

---