A Programming Style for Java

Paul Haahr
26 October 1999
(first draft: 26 May 1998)
(second draft: 31 December 1998)
(last revised: 24 July 2001)

I've been programming full-time in Java for several years, which hardly makes me an expert on the language, but I've developed a style I've become comfortable with and thought it would be worthwhile to write down. This is just my personal style, and while I've written this essay with lots of recommendations, it remains a distinctly personal view of how to write code.

This style has evolved from the style I used for C programs, with some influences from the years I spent working in Scheme and Dylan, along with the usual collection of ``little'' or domain-specific languages I've also used, such as YACC or various Unix shells. Much of my style is independent of the language being used; I believe that my Dylan and C programs have substantially the same feel as my Java programs, and that's natural to expect.

Most of my experience with Java has been in writing a bytecode to native compiler, which is a moderate-sized Java program, containing around 500 classes and 80,000 lines of code. That includes comments and boilerplate code, but I think it's a good amount to have produced in a year. My style has remained mostly consistent over that time, with a few exceptions discussed below.

All style guides are inherently rules of thumb. Rules are meant to be broken: I'm sure there are many good reasons to violate every suggestion here. When I'm about to write code which goes against my (previously uncodified) style, I think about why I'm doing something different and whether that reason is sufficient.

I assume that the reader of this essay is familiar with Java; the more general comments are independent of the language, but many are concerned with the particulars of Java.

Contents

• Basic Principles
  1. Readability is the most important attribute of style.
  2. Choose good names.
  3. Don't fight the language.
  4. Be consistent.
  5. Comment appropriately.
  6. Don't let optimization interfere with readability.
  7. Be a chameleon.


• Typography
  1. Make your code look like the examples in the JavaSoft books.
  2. Write searchable code.
  3. Break lines longer than eighty columns.
  4. Use four-space or narrower indentation.
  5. Use blank lines to identify related lines of code.
  6. Parentheses always help.


• Naming
  1. Use consistent naming conventions.
  2. Use names you can pronounce.
  3. Don't use abbreviations.
  4. Types provide good roots for variable names.
  5. Good names aren't necessarily long names.
  6. Steal names from external sources.
  7. Use sensible parts of speech.
  8. Use names with a positive sense.
  9. Name all magic numbers.
  10. Be willing to change a bad name.


• Class structure
  1. Write documentation comments for all classes and members.
  2. Group related declarations.
  3. Don't use package-qualified names except in import declarations.
  4. Import whole packages only in limited circumstances.
  5. Don't build circular package relationships.
  6. Don't overuse inheritance (especially subclassing).
  7. Don't subclass concrete classes.
  8. Keep classes, fields, and methods private until they're needed elsewhere.
  9. Use final for fields which shouldn't change .
  10. Make all non-final fields private.
  11. Support anonymous instance creation when sensible.


• Methods and Statements
  1. Each method should do one thing.
  2. Smaller methods are easier to understand.
  3. Partition methods to have short parameter lists.
  4. Declare variables when you're first ready to use them.
  5. Create new variables rather than reassigning old ones.
  6. Don't modify parameter variables.
  7. Treat side-effects cautiously.


• Errors and Exceptions
  1. Don't use exceptions for normal control flow.
  2. Don't use declared exceptions for erroneous conditions.
  3. Let the language find errors for you.
  4. Use assertions.


• Idioms
  1. Use ``while (true)'' for infinite loops.
  2. Set loop limits in for-initialization clauses.


• Other Style Guides

For printing or downloading, you may prefer to use the single page version of this essay