2005-01-14
This Style Guide[1] summarizes useful coding standards, conventions, and guidelines for writing correct, high-quality, and maintainable code in C, C++, or Java. They are based on industry standards, although often reduced to a simplified form to teach the concepts yet keep the work load reasonable. By following these principles, you will be better able to produce code that is correct, requires less debugging effort, and is easier for the graders to follow.
In the real world, code conventions are important to programmers for a number of reasons:
80 % of the lifetime cost of a piece of software goes to maintenance. Hardly any software is maintained for its whole life by the original author. Code conventions improve the readability of the software, allowing software engineers to understand new code more quickly and thoroughly.
Coding standards allow teams of programmers to more easily understand each others code and help spot errors. Rather than coding from scratch, team members are more likely to sharing and re-use code when the style and commenting conventions among team members are the same.
Some of the recommendations given in this document are generally accepted conventions and should be considered mandatory, while others are merely suggestions that may differ between styles. The ultimate goal is readability, and good is what contributes to it. In any case, there is no readability without consistency of style.
This document uses object-oriented terminology and refers to “functions” as “methods”. For the purpose of this document, a “method” is the same as a “function”.
While the code examples are given in Java, the cited principles apply to all related languages.
The following general guidelines apply to choosing identifier names in your programs:
Use full English descriptions for names.
Avoid using abbreviations. For
example, use names like firstName
,
lastName
, and
middleInitial
rather than the shorter
versions fName
, lName
,
and mi
.
Avoid unnecessarily long names.
For example, setTheLengthField
should be
shortened to setLength
. If you feel that
you cannot clearly express the meaning of a variable within
a reasonable variable name (up to about 20 characters), you
should think about restructuring your code.
Avoid names that are very similar. For example, if you
store a list of products in a variable called
perishableProducts
, it may be better to
refer to a particular product as
thisPerishableProduct
(or
thisProduct
or
product
) rather than
perishableProduct
to avoid
confusion.
Why use English names? The programming language keywords are in English, and it is difficult to read multiple languages in parallel. Even more importantly, in the real world barely any software code stays within the realm of a single language, forcing us to use English as the de-facto common denominator.
You should write your code with the aim of making it understandable to others. Others will need to read and understand your code and one of the major keys to understanding is through the use of meaningful identifier names.
By using meaningful names, you go a long way towards writing
self-documenting code. That is, code that
is understandable on its own without requiring accompanying
comments. For example, look at the following code segment and
determine for yourself that the variable names
salesTax
and incomeTax
are
preferable to tax1
and
tax2
because the names are self
documenting.
double
tax1;// sales tax rate (example of poor variable name)
double
tax2;// income tax rate (example of poor variable name)
double
salesTaxRate;// no comments required due to
double
incomeTaxRate;// self-documenting variable names
Choose meaningful names that describe what the variable is
being used for. Avoid generic names like
number
or temp
whenever
their purpose is not absolutely clear.
Compose variable names using mixed case
letters starting with a lower case letter. For
example, use salesOrder
rather than
SalesOrder
or
sales_order
.
Use plural names for arrays. For example, use
testScores
instead of
testScore
.
Exception: for
loop
counter variables are often named simply
i
, j
, or
k
, and declared local to the
for
loop whenever possible.
for
(int
i = 0; i < MAX_TEMPERATURE; i++) { boilingPoint = boilingPoint + 1; }
These conventions are common practice in the Java development community and also the naming convention for variables used by Sun for the Java core packages. Writing code that follows these conventions makes variables easy for others to distinguish from other types. They are also increasingly used in C++ and C code.
Do not declare several variables within the same statement (separated by commas), except for trivial cases.
If the meaning and use of the variable is not clear,
add an endline comment (//
…
) stating what the variable is used for
and why. However, a better solution is to choose a
meaningful name to avoid the need for the endline
comment.
Declare variables immediately before they are used, rather than declaring all variables at the top of the method.
In pre-ISO-1999 C, declare all variables at the beginning of the innermost block that delimits its intended scope. It can sometimes be a good idea to open a new block specifically for declaring variables close and limited to their local use.
Whenever possible, initialize the variable with its starting value in the declaration statement.
In pre-ISO-1999 C, if the first use is far away from the variable declaration, it is perhaps an indication of poor code design.
Use ALL_UPPER_CASE
in your
constant names, separating words with the underscore
character. For example, use TAX_RATE
rather than taxRate
or
TAXRATE
.
Avoid using literal numbers in
the code. Literal numbers like 27
that appear in the code require the reader to figure out
what 27
is being used for. Consider
using named constants for any number other than 0 and
1.
day = (3 + numberOfDays) % 7;// NO! uses literal numbers
static
final
int
WEDNESDAY = 3;static
final
int
DAYS_IN_WEEK = 7; day = (WEDNESDAY + numberOfDays) % DAYS_IN_WEEK;// Yes, self-documenting
Try to come up with meaningful method names that succinctly describe the purpose of the method, making your code self-documenting and reducing the need for additional comments.
Compose method names using mixed-case letters, beginning with a lower case letter and starting each subsequent word with an upper case letter.
Begin method names with a strong action
verb (for example, deposit
).
If the verb is not descriptive enough by itself, include a
noun (for example, addInterest
). Add
adjectives if necessary to clarify the noun (for example,
convertToAustralianDollars
).
Use the prefixes get
and
set
for getter and
setter methods. Getter functions merely
return the value of a variable; setter functions change the
value of a variable. For example, use the method names
getBalance
and
setBalance
to access or change the
variable balance
.
If the method returns a boolean
value, use is
or
has
as the prefix for the method
name. For example, use isOverdrawn
or
hasCreditLeft
for methods that return
true
or false
values. Avoid the use of the
word not
in the boolean method name,
use the !
operator instead. For example,
use !
isOverdrawn()
instead of isNotOverdrawn()
.
These conventions are common
practice. Writing code that follows these
conventions makes methods easy for others to identify. Even
though variables and methods both begin with a lower-case
letter followed by mixed case, they can easily be
differentiated from each other because method names begin with
a verb and always are immediately followed with a set of
parenthesis, for example:
moveAccount()
.
Class names are always written in mixed case like method names, but begin with an upper-case letter.
By analogy, typedef
s of
structured types should be named in the same way.
In C, struct
s and enum
s are typically named in
all-lowercase, ending with _t
. However, you
will usually want to typedef
such types.
A case could be made for naming typedef
s of non-structured types
according to C-style conventions, to distinguish them from
structured types. However, I feel it increases readability
greatly if all typedef
names begin with an upper-case
letter, to distinguish them from variable names:
class
SomeClass { … };typedef
struct
node_t {void
*content;struct
node_t *next; } Node;typedef
enum
season_t { SPRING, SUMMER, FALL, WINTER } Season;
[1] This document is evolving from a Java Style Guide by Ed Gellenbeck, Central Washington University, and benefited significantly from comments by Sébastien Jodogne.