Pure Programmer
Blue Matrix

Cluster Map

Documentation

Every program describes how to accomplish some task in the language of mathematics and logic. While high level languages help us to express programming concepts easily and clearly, they are often not the best way to explain the abstract concepts involved. This is where programming documentation comes to the rescue. Documentation in the form of program comments interspersed in the source code are a means to explain in plain English the expected workings of a program and the high level concepts involved. They are a way to include information that is not obvious or clear in the programming statements themselves.

In this site we will use a standard block of comments at the beginning of each file to explain the purpose of the program in the file. We will include the program author, the date that the program was written and any updates that were made. This last use of comments to document the update history is one that should only be used for programs that are not under source code control. For complex multi-file programs a [[source code control system]] will be a necessity and will perform the task of managing the update history of files.

Basic comments take two forms: single-line and multiple-line. Single-line comments begin with a double slash (//) and continue to the end of the current line. They can start at the beginning of the line or anywhere in the middle of a line. Multi-line comments may begin anywhere using the comment start symbol (/*) and continue until the comment end symbol (*/). All characters in the comment are ignored and not considered to be executable program content.

The following are examples of comments.

// This is a single line comment

/* This is an example
   of a multi-line comment */

Each program file, class or function/method should have a comment preceding it that describes the purpose and typical usage of the item being documented. Comments should document the high-level behavior and not get involved in the specifics of the current implementation. Implementation details can change but the interface described by the comment should rarely change. It also helps to know how the program, class or function/method is intended to perform when the code itself is found to have a bug. The following is an example of what a program file comment might look like.

/*********************************************************************
 * This program computes ...
 *
 * Copyright © 2023 Richard Lesh.  All rights reserved.
 ********************************************************************/

References