Home
Independent
Programming
  1. Software Standards Specification
  2. Software Requirements Definition
  3. Software Best Practices
  4. Input Validation
  5. Output Validation
  6. Cookie Requirements
  7. Access Failure Error Checking
  8. Buffer Overflow
  9. Code Structure
  10. Software Functions
  11. Software Modules
  12. Requirements for Variables
  13. Software Code Comment Requirements
  14. Quality Code Requirements
  15. Software Code Review
  16. Software Code Testing Requirements
  17. Software Change Control

    Security Best Practices

  18. Secure Functional Requirements
  19. Account Creation
  20. Change Password
  21. Forgot Password
  22. Personal Question
  23. Contact Webmaster
  24. CAPTCHA Tests
  25. Answer Verification
Programming
Independent
Home

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.