PDF version of this document

Programmer's Manual and Documentation

The code which may be very readable to its creator is not always as manageable and understandable to another programmer that wishes to extend, improve or maintain it. Therefore, some more abstract views of the system, along with some description in natural language can save a lot of time and effort. The following are some basic suggestions:

1. It needs to be assured that the code is well documented, preferably with comments where appropriate.
2. A functional and modular summary is necessary to give a system overview. This can also prove to be useful if we want to re-use the code, let us say, for some new chess application. Finding the appropriate functions fairly trivial in this way.
3. A diagram of the system structure would be highly appreciated by the next person to familiarise himself/herself with the code structure. It often proves to be crucial for the understanding of the interactions within it.
4. A report of how the system works as a whole, how to compile it, platform/OS dependent code and debugging tools are a necessity. It is a very common phenomenon for a programmer to find himself/herself lost with a piece of code that is unreadable, unusable or lacks the compilation facilities.