Writing Internal Documentation

Internal documentation addresses and maintains the program understanding and is intended for current and future developers. Current developers document thoughts and rationales behind a program, so future developers can gain understanding of the program, without resorting to reverse engineering (either manual or “automatic”). We know that programs that are documented in this way are likely to be better programs [5] because they have a tendency to be reflected upon more carefully during coding. In addition, maintenance is an important and time-consuming discipline during software development. Often a program lives for a long time, but during this lifetime, the program is subject to changes, such as bug fixes and enhancements. The developers that work on a program may vary during its lifespan. Future programmers such as newcomers to a software project and maintainers will have a hard time understanding the program if no documentation is available. As time passes the understanding of the program will disappear if this understanding is not maintained in some way – the developers will simply forget why things where done as they were. Even the original developers will forget the details of a program if no documentation has been written.