This page was migrated from a javaranch.com.jsp
Java Programming Style Guide
Introduction
1 Formatting
2 Identifiers
3 Coding
4 Self-Documenting Code
Introduction
The Java language gives you all the room you need to write code that would be very
difficult for others to understand. Java also permits you to write code that is very easy
to understand. Most development teams would prefer the latter.
A style guide provides provides a map so that the code generated by a group of programmers
will be consistent and, therefore, easier to read and maintain. Many people do not care for the
style guide offered by Sun.
This document is one alternative.
This document covers most areas where there could be confusion or difference of opinion.
Areas that have never been a problem in our experience are undocumented, but we try to provide
at least one example to demonstrate proper use somewhere in the document.
1 - Formatting
1.1 - Indentation
<strong>All indenting is done with spaces, not tabs. All indents are four spaces.</strong>
<em>Reasoning: All programs work well with spaces. Most programs will mix tabs
and spaces so that some lines are indented with spaces and some with tabs. If your
tabbing is set to 4 and you share a file with someone that has tabbing set to 8,
everything comes out goofy.</em>
<strong>Matching braces always line up vertically in the same column as their construct.</strong>
example:
<strong>All if, while and for statements must use braces even if they control
just one statement.</strong>
<em>Reasoning: Consistency is easier to read. Plus, less editing is involved
if lines of code are added or removed.</em>
1.2 - Spacing
<strong>All method names should be immediately followed by a left parenthesis.
</strong>
<strong>All array dereferences should be immediately followed by a left square bracket.</strong>
<strong>Binary operators should have a space on either side.</strong>
<strong>Unary operators should be immediately preceded or followed by their operand.</strong>
<strong>Commas and semicolons are always followed by whitespace.</strong>
<strong>All casts should be written with no spaces. </strong>
<strong>The keywords <code>if</code>, <code>while</code>, <code>for</code>, <code>switch</code>, and <code>catch</code> must be followed by a space.</strong>
1.3 - Class Member Ordering
1.4 - Maximum Line Length
<strong>Avoid making lines longer than 120 characters. If your code starts to get indented way to
the right, consider breaking your code into more methods.</strong>
<em>Reasoning: Editors and printing facilities used by most programmers can easily
handle 120 characters. Longer lines can be frustrating to work with.</em>
1.5 - Parentheses
<strong>Parentheses should be used in expressions not only to specify order of precedence, but
also to help simplify the expression. When in doubt, parenthesize.</strong>
2 - Identifiers
<strong>All identifiers use letters ('A' through 'Z' and 'a' through 'z') and numbers ('0'
through '9') only. No underscores, dollar signs or non-ascii characters.</strong>
2.1 - Classes and Interfaces
<strong>All class and interface identifiers will use mixed case. The first letter
of each word in the name will be uppercase, including the first letter of the name.
All other letters will be in lowercase, except in the case of an acronym,
which will be all upper case.</strong>
Examples:
2.2 - Packages
<strong>Package names will use lower case characters only. Try to keep the length under eight
(8) characters. Multi-word package names should be avoided.</strong>
Examples:
2.3 - All Other Identifiers
<strong>All other identifiers, including (but not limited to) fields, local variables,
methods and parameters, will use the following naming convention.
This includes identifiers for constants.</strong>
<em>Reasoning: Using all upper case, as traditionally done in C, is a violation of OO abstraction.
For example, a variable which starts out as a constant may be refactored later to not be a constant.</em>
<strong>The first letter of each word in the name will be uppercase, except for the first letter of
the name. All other letters will be in lowercase, except in the case of an embedded
acronym, which will be all uppercase. Leading acronyms are all lower case.</strong>
Examples:
2.3.1 Hungarian Notation and Scope Identification
<strong>Hungarian notation and scope identification are not allowed.</strong>
<em>Reasoning: Hungarian Notation, which specifies type as part of the identifier, violates OO abstraction. Scope identification specifies scope as part of the identifier, which also violates OO abstraction.</em>
2.3.2 Test Code
<strong>Test code is permitted to use underscores in identifiers for methods and fields.</strong>
<em>Code for testing other code often needs to be able to refer to existing identifiers, but also be able to append other qualifiers to the name. This is easier to read if an additional delimiter is allowed.</em>
Example:
Code to test a method <code>double eatSomePie(double amount)</code> may use variables such as:
<code>eatSomePie_count</code>
<code>eatSomePie_amount</code>
<code>eatSomePie_return</code>
<code>eatSomePie_exception</code>
3 - Coding
3.1 - Constructs to Avoid
3.1.1 - Never use do..while
<strong>Do not use <code>do..while</code> loops.</strong>
<em>Reasoning: Consider that the programmer looking at your code is probably examining
each method starting at the top and working down. When encountering a loop, the first
thing the programmer wants to know is what terminates the loop. If you have that logic at
the bottom, it is harder to read. Further, many less experienced programmers are not
familiar with do..while, but may be required to modify your code.</em>
So rather than:
use:
3.1.2 - Never use <code>return</code> in the middle of a method
<strong><code>return</code> is to be used at the end of a method only.</strong>
<em>Reasoning: Using <code>return</code> in the middle of a method makes it difficult to
later break the method into smaller methods. It also forces the developer to consider more
than one exit point to a method. </em>
3.1.3 - Never use <code>continue</code>
<strong>Never use <code>continue</code>.</strong>
<em>Reasoning: Using <code>continue</code> makes it difficult to later break the
construct into smaller constructs or methods. It also forces the developer to consider
more than one end point for a construct. </em>
3.1.4 - Never use <code>break</code> other than in a switch statement
<strong><code>break</code> is used only for switch statement control.</strong>
<em>Reasoning: Using <code>break</code>, other than for switch statement control, makes
it difficult to later break a construct into smaller constructs or methods. It also forces
the developer to consider more than one end point for a construct. </em>
3.2 - Do Not Compound Increment or Decrement Operators
<strong>Use a separate line for an increment or decrement.</strong>
<em>Reasoning: Compounding increment or decrement operators into
method calls or math is not clear to less experienced programmers who
may be required to modify your code.</em>
Examples:
Note: i++ and ++i are equally fast, and i++ seems more consistent with the
rest of the language. Since the above prevents any use of a case where ++i
could make a difference, never use pre- increment/decrement.
3.3 - Initialization
<strong>Declare variables as close as possible to where they are used.</strong>
Examples:
3.4 - Access
<strong>All fields must be private, except for some constants.</strong>
4 - Self-Documenting Code
<strong>Rather than trying to document how you perform a complex algorithm, try to make the
algorithm easier to read by introducing more identifiers. This helps in the future in case the
algorithm changes but someone forgets to change the documentation.</strong>
Example:
Or: