Style
26-Jul-16
About the book




This book is a team effort by
many good programmers, not just
one person’s opinions
The rules have been widely
distributed and commented upon
The rules reflect widespread and
accepted practices
And no, I don’t agree with
everything in the book!
2
Rule 1: Adhere to the style of the original


Consistent style is very important
Most times, you will enter an ongoing project, with
established style rules



Follow them even if you don’t like them
Don’t try to establish “better” style rules
 It won’t work anyway
 There may be reasons you don’t know about
If a project has mixed styles with no consistency,
you might try to get people to agree on one
3
Rule 3: Do it right the first time



You’re working on a large project, so you use good
style...
...but you need a tool to help you do one little job, so
you slap it together quickly
Guess which program will be around longer and used
by more people?
4
Rule 5: Indent nested code




Always indent statements that are nested inside
(under the control of) another statement
if (itemCost <= bankBalance) {
writeCheck(itemCost);
bankBalance = bankBalance - itemCost;
}
while (seconds > 0) {
System.out.print(seconds + "...");
seconds = seconds - 1;
}
Indentation should be consistent throughout the
program

4 spaces has become more-or-less standard
5
Rule 6: Break up long lines





Scrolling a window horizontally is a pain!
When you print on standard paper, long lines are either
cut off or wrap in bad places
I have long used a 72 character limit
Some editors will show you a limit line
Various suggestions:



Break after, not before, operators
Line up parameters to a method
Don’t indent the second line of a control statement so that it
lines up with the statements being controlled
6
Rule 8: Don’t use “hard” tabs



Once upon a time, you could depend on tab stops
every eight character positions
Today, every editor has its own idea of where and how
to set tab stops
If you change editors, your nice indentation gets
ruined




It’s worse if you use both tabs and spaces
I have learned this one the hard way!
A hard tab is an actual tab character in your text
Good editors can be set to use soft tabs (your tab
characters are replaced with spaces)

BlueJ uses only soft tabs; Eclipse can do either
7
Rule 9:Use meaningful names





Names should be chosen very carefully, to indicate the
purpose of a variable or method
If the purpose changes, the variable or method should
be renamed
It is worthwhile spending a little time choosing the best
name
Long, multiword names are common in Java
Eclipse makes it very easy to rename things
8
Rule 10: Use familiar names


Where common terminology exists, use it; don’t make
up your own
Example from the book: If your users refer to
“customers,” your program should use the name
Customer, not Client
9
Rule 11: Question excessively
long names



Variables should be used for a single purpose
Methods should do one simple, clearly defined thing
If a descriptive name is overly long, maybe the
variable or method is trying to serve too many
purposes
10
Meaningful names: exceptions I



It is common practice to use i as the index of a forloop, j as the index of an inner loop, and k as the
index of a third-level loop
This is almost always better than trying to come up
with a meaningful name
Example:

for (int i = 1; i <= 10; i++) {
for (int j = 1, j <= 10; j++) {
System.out.println(" " + (i * j));
}
}
11
Meaningful names: exceptions II

Method variables may be given short, simple names,
if:



The purpose of the variable is obvious from context, and
The variable is used only briefly, in a small part of the
program
But never use meaningless names for fields (class or
instance variables)
12
Rule 28: Use standard names for
“throwaway” variables

If variables have no special meaning, you can use
names that reflect their types


For example, if you are writing a general method to work
with any strings, you might name them string1, string2,
etc.
Alternatively, you can use very short names



s, t, u, or s1, s2, etc. are often used for Strings
p, q, r, s are often used for booleans
w, x, y, z are often used for real numbers
13
Rule 12: Join the “vowel generation”

In more primitive languages, names were often limited
to 8 or so characters




This led to names like maxVolum and lngPlyng
The usual rule was to leave out vowels, starting from the right
Such names are harder to read and to remember
Do not leave out vowels, or otherwise use
unusual abbreviations, in Java!
14
Naming classes and interfaces

Rule 18: Capitalize the first letter of each word, including
the first:
PrintStream, Person, ExemptEmployee

Rule 19: Use nouns to name classes:
ExemptEmployee, CustomerAccount


Classes are supposed to represent things
Rule 20: Use adjectives to name interfaces:
Comparable, Printable

Interfaces are supposed to represent features
15
Naming variables

Rule 25: Capitalize the first letter of each word except
the first:
total, maxValue

Rule 26: Use nouns to name variables:
balance, outputLine

Variables are supposed to represent values
16
Naming methods

Rule 22: Capitalize the first letter of each word except
the first:
display, displayImage


Methods are capitalized the same as variables
Rule 23: Use verbs when naming methods:
displayImage, computeBalance

Methods are supposed to do something
17
Rule 13: Capitalize only the first
letter in acronyms




In names, write acronyms such as GUI and API as
Gui and Api
Examples: setDstOffset,, displayAsHtml,,
loadXmlDocument
Since capital letters are used to separate names, this
rule helps avoid confusion
Sun’s APIs don’t always follow this convention
18
Naming constants


A constant is an identifier whose value, once given,
cannot be changed
Constants are written with the keyword final, for
example:

final int FIVE = 5;
 final float AVOGADROS_NUMBER = 6.022E23;
Rule 31: Constants are written in ALL_CAPITALS,

with underscores between words
Exception: color names, such as Color.pink



Colors were defined before conventions were established
However, Java 1.4 adds properly capitalized names for
colors, such as Color.PINK
19
Kinds of comments


“Standard” (C-style) comments: /* ... */
One-line and end-line comments:
// a one-line comment is on a line by itself
x = 0; // an end-line comment follows code
 All of the above are “internal” comments, seen only by
someone looking at your code
 Don’t overcomment; not every line needs a comment!
 Internal comments are only for maintainers
 But avoid things that would embarrass you to a user!

Documentation (javadoc) comments: /** ... */


These are meant to be seen by the entire world!
Documentation comments are covered elsewhere
20
Which kind of internal comment?

Rule 36: Use “standard” (/*...*/) comments to
comment out code without removing it.


However, this assumes you are using a simple text editor,
because it saves typing // over and over again
This is a bad rule if you are using a decent IDE

Standard comments cannot be nested, so it’s tricky
commenting out code with comments


One-line comments don’t have this problem
Both BlueJ and Eclipse make it very easy to use one-line
(//...) comments
21
Explaining the code I

Rule 59: Add internal comments only if they will
aid in understanding your code.



Don’t repeat the javadoc comments
Don’t put in comments to explain things that are obvious
from the code
Don’t put in irrelevant or useless comments


// Go Eagles!!!!
Always put /* ... */ comments before the code they
describe, never after the code
22
Explaining the code II

Rule 37: Use one-line comments to explain
implementation details.

One-line comments are also good for writing reminders for
yourself about things you still need to work on


You can use one-line comments to tell what the next several
lines of code are going to do


// These assertions should be replaced by Exceptions
// Put this Vehicle in a random location
Usually, though, it’s better to put the commented code in a
method

vehicle.putInRandomLocation();
23
End-line comments I

Rule 62: Explain local variable declarations with an
end-line comment.



int edgeDistance; // distance to the nearest edge
But don’t let your lines get too long
And Rule 64 says: Label closing braces in highly
nested control structures.


} // end switch
} // end if
} // end for j
} // end for i
Better yet, avoid highly nested control structures
24
End-line comments II

I also find end-line comments useful for an else that is a
long way from its if:


if (distance > 5) {
... a lot of code in between ...
}
else { // distance <= 5
...
}
But now that we have assert statements, this is even better:

...
else {
assert distance <= 5;
...
}
25
Flagging unresolved issues


Rule 63: Establish and use a set of keywords to flag
unresolved issues.
Eclipse uses these three (you can add more):




TODO for things you would like to do in the future
FIXME for things which are broken and you need to fix, but
you aren’t working on at the moment
XXX for things that are arguably broken and you need to
think about some more before you do anything
Example: // FIXME Doesn’t test for null values
26
Intentionally missing break

Rule 65: Add a “fall-through” comment between two
case labels of a switch statement, if no break
statement separates those labels.


The switch statement is so badly designed that forgetting the
break is a common error
To keep an intentionally missing break from being
“corrected,” add a comment
27
Label empty statements


Sometimes you intentionally use a loop with an
empty statement body
Rule 66: Label empty statements.
while ((c = reader.read()) == space) ;
// Empty body
 This is because the semicolon is small and easy to
overlook

I prefer a different solution: use an empty block as
the statement body
while ((c = reader.read()) == space) { }
28
Don’t repeat the code


Rule 60: Describe why the code is doing what it does,
not what the code is doing.
Another way of saying this is:
Comments should not echo code.


Here’s a typical example of a bad comment:
count = 0; // set count to zero
You should assume that anyone reading your internal
comments knows some Java!
29
Use the active voice

Rule 34: Use the active voice, and omit needless
words




// zero out the array
// each of the elements of the array is set to
// zero by the following loop
Writing comments is still writing--all the rules for
good writing apply to comments
Best reference: The Elements of Style, by Strunk
and White
30
Debugging statements


We sometimes put in debugging statements that we
plan to remove afterwards
Simple trick: start these “temporary” statements in
the first column, so you can find them easily
boolean legalLocation(int row, int col) {
System.out.println("In legalLocation: " + row + " " + col);
return row >= 0 && row < numRows &&
column >= 0 && column < numCols;
}

Another option:

final boolean debugging = true;
...
if (debugging) System.out.println(...)
31
The End
32
The End
“If you don’t think carefully, you might think that
programming is just typing statements in
programming language.”
--Ward Cunningham
33