|
A Word on Style |
|
Introduction
Of the many skills taught in an introductory computer science course, one of
the most important--and, unfortunately, one of the most neglected--is the use
of proper style. In the vast majority of high school classrooms, style receives
virtually no attention. Teachers often would rather teach "the language
itself" than try to impose stylistic considerations on their students.
Students, for their part, tend to ignore what style they are taught in favor of
whatever seems convenient or appropriate to them at the time.
However tempting it may be to ignore style completely-or at least give it a
tertiary role-it is vital that it be taught and enforced at the early stages of
C++ education. Code formatting and documentation becomes habitual very quickly,
and it is the instructor's responsibility to ensure that stylistic habits
formed are good ones.
Of course, this emphasis on style is not recommended simply for the sake of
code appearance. The benefits of consistently well formatted code are many.
First, a well-styled program is more likely to work correctly-a fact that any
experienced C++ programmer will vouch for. Second, well-formatted code is much
easier to debug, especially if people other than the original programmer are
involved in the debugging. Finally, higher level computer science classes and
technical companies all require that their programmers write properly styled
code.
Unfortunately, there is no single style that is "correct." To be
sure, the various elements of C++ code can all be formatted a number of ways
and still be in keeping with accepted standards. The intent of this section,
then, is simply to discuss correct and incorrect stylistic elements. We then
charge each individual student to choose a correct style-based on personal
preference-and then use it consistently, from line to line and from program to
program.
Indentation
Indentation size should be two spaces. Obviously, it must be the same
throughout the program.
The size of all indentation levels should be equal. Each group of
statements that is indented must be indented one full level. Nothing at all
should be "inbetween" indentation levels.
Tabs should never be used for indenting. The use of tabs for
indenting was common when all C code was indented eight spaces. However, since
that is no longer the case, only hard spaces should be used to indent.
The first indenting level is the first column of the screen. That
means all classes and functions should be declared beginning on the first
column, and their bodies should be on the first level of indentation.
Comments
Either C or C++ style comments are acceptable. In C++, it is most common
to use C-style comments (/* */) when writing a block of comments and C++ style
comments (//) to comment a line. Some people use the C++ style exclusively,
placing a // before each line of a blocked comment. Either scheme is
appropriate.
Every program and function should be preceded by appropriate
documentation, including the function of the function and its parameters
and return value. Some programming groups enforce this rule strictly and others
couldn't care less. Obviously, the programmer must meet the requirements of his
employer or teacher.
Whenever it is unclear what a block of code does, it should be commented.
This stands to reason, and is universally accepted and expected. An essay is
not necessary, but a few descriptive words are appropriate.
Brace Style
Brace style is undoubtedly one of the most inflammatory issues surrounding C++
formatting. Kernighan and Ritchie, authors of The C Programming Language,
offer this advice: "The position of braces is less important, although
people hold passionate beliefs. We have chosen one of several popular styles.
Pick a style that suits you, then use it consistently." The following
three styles are popular and all acceptable:
|
Extended Braces
(Allman Style) |
Kernighan and
Ritchie (One True Brace Style or 1TBS) |
Indented Braces
(Whitesmith's Style) |
|
|
|
|
It is probably worth noting that there is a faction which says the Allman
Style should be used to enclose a new scope (functions, classes, etc.) whereas
the One True Brace Style should be used for loops and if statements. Others
have criticized this scheme, saying it isn't self-consistent. Still, it has a
large enough following that it is considered an acceptable convention.
Naming Conventions
Variable and function names generally always begin with a lowercase letter.
Some programmers make the entire name lowercase, even if it consists of
multiple words (int nextreturnvalue).
Others begin subsequent words with an uppercase letter (int nextReturnValue). Many C programmers
use underscores to separate words (int next_return_value).
All three are acceptable; this course uses the second. Again, pick one and
stick with it.
Classes and other abstract data types generally begin with an uppercase
letter, after which any of the options for variable names are acceptable (class SuperCoolClass).
Constants should be named entirely in uppercase (const int MAXLEN = 80).
Variable names should be descriptive when their function is not clear.
Of course, this is taken to different degrees by different programmers. In C,
variables are traditionally given concise names, such as i for a loop index
variable or tmp for any temporary variable. This is a matter of personal
preference.
Function and class names should always be descriptive, although they
should not be unnecessarily verbose. gn()
is probably too short, whereas getNumberFromUser()
is ridiculous. getnum()
would be most appropriate.
Functions
Functions must have a single, clear purpose and shouldn't be too long. A
good rule of thumb is that a function shouldn't be much longer than a full
screen length.
All functions must be prototyped, and variables names should be given in
the prototype. That is, when you declare a function at the top of the
program, you should not just give the types of the parameters, (void bob(int)), but the name as well (void bob(int num)).
Leave an empty line between classes and functions. Your code is
impossible to read if you don't do this. It is absolutely required. On the
other hand, lines of asterisks or dashes are not usually placed between
functions as they occasionally are in other languages.
Blocking Examples
switch statements
may be indented two ways. Whenever space permits, the scheme on the left
should be used, but lines should never exceed 80 characters. In these examples,
we use the Allman style of braces, though the K&R or Whitesmith's style
could be used as well.
|
|
|
for, while, do-while, and if-else statements all follow the
standard indenting rules. The appendices have examples of these
constructions with the Allman brace style; again, the others are acceptable.
|
|
|
|
The body of while
and for
statements doesn't need curly braces if they consist of only one statement.
Curly braces are always necessary for do-while loops. You may indent
the single statement on the next line or place it on the same line as the
control statement at your option.
|
|
|
|
Continue to: Introduction / Prev / Next