Software Code Comment Requirements

This page provides information about the requirements for commenting code and should be used as the code documentation standard.

Software Code Documentation Requirements

• Program and Technical Documentation
  • Every function or procedure must have a comment header which documents:
    • Its use.
    • Its input parameters and their meaning.
    • Its output parameters.
    • Its creation date.
    • Data structures used or modified inside and outside the module.
    • Name of the creator.
  • A module list with list of each procedure or function in each module must be maintained.
  • Each module shall have a header to describe its function, included procedures or functions, and any additional information about what is needed to use the module.
  • Version numbers for the software and modules shall be maintained and kept on record.
  • Changes will be recorded in the code along with date of the change, reason for the change, and who made the change.
  • Functions must be named in a way that makes sense in describing its use.
  • There must be enough comments in the code so the program can be understood by reading the comments. There must be at least one meaningful comments averaging one for each three lines of code, including comments at headers of functions.
  • All file formats must be documented.
  • All database formats/schemas must be documented.
  • The program version number will be displayed when the program begins to run.
  • A copyright notice will be displayed at the beginning of each module.
  • Variables must have meaningful names excluding variables used for counting or looping.
• User Documentation
  • Documentation must be designed appropriate for the skill level of the user and should not assume technical expertise unless expertise is assured.
  • User documentation must inform users about how to use the program and provide information about available commands and screens. User manuals must be written as simply and direct as possible.
  • User manuals must comply with user manual guidelines and instructions.
  • End users must have a part in the development or review of user manuals before they are finalized.
  • The owner of the documentation including user manuals must be established with set responsibility for maintaining the manuals and system maintenance procedures.
  • A structured training program must be created.