Internal Documentation

2.3 Internally document the code by adding comments

What is a Comment?
A comment is explanatory text put in a program to help someone reading it to better understand what the program should do, eg: someone given the task of maintaining the software at some future date.

You do not have to comment every line of a program because if your program is well written, most of it should be easy to understand. However, you should comment any part of the program where the code is not straightforward.

For complex programs, more rather than less comments are preferred.

Comments can contain any characters, and can take up as many lines as needed. Comments are for human eyes only and will be ignored by an interpreter or compiler because including comments does not in any way change of affect how the program runs. This, however, gives rise to the argument that if comments do not actually do anything why should they be included at all.

It is usually a good idea to have a commented program identification section at the start of each program and also each sub-program.

Types of Comments

Prefacing – Involves the programmer adding short explanatory information at the start of the major components of a program, eg. a short preface can be added at the start of each function.

Comment-Driven Development (CDD) – Involves programmers copying the detailed algorithm for the part of the program under development and translating the pseudo-code into program code.

Revision History – Involves the chief programmer maintaining a record of the parts of the program being worked on and may include information such as the name of the programmer and dates of changes as well as changes made.

Tagging – Involves programmers making sure that any commonly use punctuation such as { are tagged with a begin with the equivalent } tagged with an end

How to Comment

Use revision history comments – Showing when a change was made and more importantly why the change was needed

Use descriptive line comments – These comments should tie in with other program design documentation such as the reference numbers used in Structure Charts and the names used.

Comment during live coding

Keep comments short and simple

Use working comments to ‘prevent’ or ‘allow’ lines of code from being executed for testing and debugging purposes.

How NOT to Comment

Do not underestimate your audience. Whoever reads your comment will also be a developer, hopefully a competent one. There is no need for comments along the lines of “This is a variable.”

Do not over-comment. Beyond describing your program unit and summarising logical blocks within it, restrict your commenting to explaining complicated sections and highlighting important facts that may otherwise be missed.

Do not comment out redundant code. If it is no longer needed then delete it. The exception here is code that is being used for testing purposes.

Comments in JavaScript

Single line comments start with //

Multi line comments start with /* and end with */

In Javascript comments cane also be placed after lines of code.

Internal Documentation for Larger Projects

//—————————————————————–
// Program Identification Section
//—————————————————————–
// Program FileName: The current version name of the program
// Version No.: Numeric value that changes with each version
// Date Written: Date of the last change to the code
// Author: Name of the programmer
// Language: The programming language used
//—————————————————————-
// Description: A brief description of the program’s purpose
//—————————————————————-

For each function type the following:
// Module Ref No: Reference number
// Module Name: The name of the procedure
// Description: A brief description of the procedure

Next: Example 1