Programming Style and Documentation

Good programming style and proper documentation make a program easy to read and help programmers prevent errors.

Programming style deals with what programs look like. A program could compile and run properly even if you wrote it on one line only, but writing it that way would be bad program- documentation ming style because it would be hard to read. Documentation is the body of explanatory remarks and comments pertaining to a program. Programming style and documentation are as important as coding. Good programming style and appropriate documentation reduce the chance of errors and make programs easy to read. So far you have learned some good pro­gramming styles. This section summarizes them and gives several guidelines about how to use them. More detailed guidelines on programming style and documentation can be found in Supplement I.E on the Companion Website.

1. Appropriate Comments and Comment Styles

Include a summary at the beginning of the program to explain what the program does, its key features, and any unique techniques it uses. In a long program, you should also include comments that introduce each major step and explain anything that is difficult to read. It is important to make comments concise so that they do not crowd the program or make it difficult to read.

2. Proper Indentation and Spacing

A consistent indentation style makes programs clear and easy to read, debug, and maintain.  Indentation is used to illustrate the structural relationships between a program’s components or statements. C++ compiler can read the program even if all the statements are in a straight line, but properly aligned code is easier to read and maintain. Indent each subcomponent or statement two spaces more than the construct within which it is nested.

A single space should be added on both sides of a binary operator, as shown here:

A single line space should be used to separate segments of the code to make the program easier to read.

Source: Liang Y. Daniel (2013), Introduction to programming with C++, Pearson; 3rd edition.

Leave a Reply

Your email address will not be published. Required fields are marked *