Program Documentation

Any written text, illustrations or video that describe a software or program to its users is called program or software document. User can be anyone from a programmer, system analyst and administrator to end user. At various stages of development multiple documents may be created for different users. In fact, software documentation is a critical process in the overall software development process.

In modular programming documentation becomes even more important because different modules of the software are developed by different teams. If anyone other than the development team wants to or needs to understand a module, good and detailed documentation will make the task easier.

These are some guidelines for creating the documents −

• Documentation should be from the point of view of the reader
• Document should be unambiguous
• There should be no repetition
• Industry standards should be used
• Documents should always be updated
• Any outdated document should be phased out after due recording of the phase out

Advantages of Documentation

These are some of the advantages of providing program documentation −

• Keeps track of all parts of a software or program
• Maintenance is easier
• Programmers other than the developer can understand all aspects of software
• Improves overall quality of the software
• Assists in user training
• Ensures knowledge de-centralization, cutting costs and effort if people leave the system abruptly

Example Documents

A software can have many types of documents associated with it. Some of the important ones include −

• User manual − It describes instructions and procedures for end users to use the different features of the software.
• Operational manual − It lists and describes all the operations being carried out and their inter-dependencies.
• Design Document − It gives an overview of the software and describes design elements in detail. It documents details like data flow diagrams, entity relationship diagrams, etc.
• Requirements Document − It has a list of all the requirements of the system as well as an analysis of viability of the requirements. It can have user cases, reallife scenarios, etc.
• Technical Documentation − It is a documentation of actual programming components like algorithms, flowcharts, program codes, functional modules, etc.
• Testing Document − It records test plan, test cases, validation plan, verification plan, test results, etc. Testing is one phase of software development that needs intensive documentation.
• List of Known Bugs − Every software has bugs or errors that cannot be removed because either they were discovered very late or are harmless or will take more effort and time than necessary to rectify. These bugs are listed with program documentation so that they may be removed at a later date. Also they help the users, implementers and maintenance people if the bug is activated.

Programming and Documentation Style Requirements

Here is a list of four categories of documentation to be considered:

1. “External” Documentation: In programming classes, the comprehensive set of documents that detail the design, development, and structure of a program are usually condensed into a comparatively brief ‘block comment’ at the top of the source code. This “external” documentation will minimally include:
   1. Your name, the course name/number, assignment name/number, instructor’s name, and due date.
   2. Detailed description of the problem the program was written to solve, including the techniques (e.g., algorithms) used to solve the problem.
   3. The program’s operational requirements: Which language system you used, special compilation information, where the input can be located on disk, etc.
   4. Required features of the assignment that you were not able to include, and/or information about bugs that are still known to exist.

1. Class Documentation: When writing a class in an object–oriented programming language, it should be preceded by a block comment minimally containing the following:
   1. The name of the class, your name, the names of any external packages upon which your class depends, the name of the package of classes containing this class (if any), and inheritance information.
   2. An explanation of purpose of the class.
   3. Names and very brief descriptions of the class and instance constants and variables.
   4. Names and very brief descriptions of constructors as well as the implemented class and instance methods.

• Internal Documentation: The details of the program are explained by comments placed within the code. The internal documentation should minimally include the following:
  1. A ‘block comment’ should be placed at the head of every method (a.k.a., function or subprogram). This will include the method name; the purpose of the method; the method’s pre– and post–conditions; the method’s return value (if any); and a list of all parameters, including direction of information transfer (into this method, out from the method back to the calling method, or both), and their purposes.
  2. Meaningful identifier names. In a nod to tradition, simple loop variables may have single letter variable names, but all others should be meaningful. Never use nonstandard abbreviations. If your language has accepted naming conventions, learn and follow them.
  3. Each variable and constant must have a brief comment next to its declaration that explains its purpose. This applies to all variables, as well as to fields of structure declarations.
  4. Complex sections of code and any other parts of the program that need some explanation should have comments just ahead of them or embedded in them.

1. Miscellaneous Requirements:
   1. Write programs with appropriate modularity; that is, create classes when appropriate, write methods that accomplish limited, well-defined tasks, etc.
   2. Global/public variables should never be used in your programs for my classes unless I have approved their use for your particular situation.
   3. Be generous with your use of “white space” (blank lines) to set off logically related sections of code.
   4. Indent bodies of methods, loops and IF statements, and do so with a single, consistent style.
   5. Like global variables, unconditional branching (e.g., goto) may not be used in your programs unless I have approved its use for your particular situation.