The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 4 : Commenting

PART 2 : COMMENTING AND NAMING

CHAPTER 4 : Commenting
4.1 Commenting fundamentals
4.2 Comment types
4.3 Header comments
4.4 File Header comment
4.5 Function header comments
4.6 Block comments
4.7 Trailing comments
4.8 Commenting data
4.9 The preprocessor and comments
4.10 Summary 

<--Prev page | Next page -->

4.2 Comment types

Comments can be used for different purposes in different parts of the program. They fall into one of three categories: header comments, block comments and trailing comments, which describe successively smaller areas of code.

Header comments are used at the start of a major item, acting as an introduction and helping the reader to understand, navigate and use the code beneath it. They are typified by being structured into specified sections (eg. inputs, outputs, etc.) and occupy a number of lines (typically between 10 and 50).

As header comments associate more closely with the code below them, they can be positioned to emphasize this fact.

Header comments are discussed further below, (see 4.3 to 4.5).

Block comments are effectively small-scale headers, describing a small section of code, such as one 'chunk'. They are typified by containing unstructured prose, and occupy few, complete lines (typically between 1 and 5).

They may describe the code above them, summarizing the current status, they may describe the code below detailing what is to happen, or they may combine the two: "All windows are now open, so paint in the forms".

Block comments are discussed further below (see 4.6).

Trailing comments describe the action of one line of code. They typically appear on the same line as the code they describe, although they can appear immediately before or after it. They are typically very brief and are written in the present tense.

<--Prev page | Next page -->