Thursday, April 7, 2011

Coding Conventions

This is a page to collect our "best practices" for developing agile code (i.e. code that is testable, maintainable, understandable, etc).  It is a work in progress, add to it as you go.  If you don't understand something or disagree, speak up, ask questions, or rewrite it.
Josh Bloch himself suggests we don't look to Sun for conventions ("I wouldn't take that document too seriously. It is not actively maintained or used at Sun.")
For example of others' "best practices" have a look at:


Build Before Committing

If it doesn't work on your PC it will break the build.

Consistent Dev Env

Fixing a broken build is always highest priority

Commit Often (and rollback often)

If In Doubt, Spike It Out (on a branch)

Fast Builds


Prefer Molecular over Atomic Tests

No Prod Code Just for Tests

  • Code needs to be testable but not exist solely for testing

Shared Code Ownership

All Prod Code is Paired (or reviewed)

See Pair Programming

No Individual Code Ownership

The team owns the code.  See

Changing the following is a team decision:

  • Reducing Coverage
  • Changing Checkstyle Rules
  • Upgrading/Adding Dependencies (libraries/plugins)

Coding Standards (what to code)

Why the need for common coding standards?  See

Follow Naming Standards

  • For tests use dummy*, stub*, and mock*, see Unit Testing Tips and Tricks
  • Concrete classes are named with interface name + "Impl" suffix. Don't prefix interfaces with "I".
    • e.g. Use Thingy + ThingyImpl instead of IThingy + Thingy
  • Use the following suffixes for tests:
    • *UnitTest - for testing one or more units while mocking out other systems/components
    • *IntegrationTest - for testing integration with other systems/components
    • *SmokeTest - for quick happy path tests
    • *FunctionalTest - for end-to-end test that prove user requirements

Avoid Nulls


Avoid Inheritance of Implementation (i.e. avoid "abstract" classes)

Prefer Delegation over Inheritance.
See Why Extends is Evil

Avoid Static Methods

Static methods are not testable

Avoid Inner Classes

Inner classes generally reduce readability, though in some cases they may increase readability.  Use them sparingly.

Keep Classes and Methods Small

Use Outlandish Class Names

Avoid "new"

  • introduces tight coupling
  • without an injection framework, try to limit the use of "new" in prod code to field declarations so that tests can inject mocks/dummies/stubs.

Prefer Unchecked (Runtime) Exceptions over Checked

Think carefully whether you need a checked exception.
See Chapter 7: "Error Handling" of Clean Code

Isolate 3rd Party code behind Boundaries

See Chapter 8: "Boundaries" of Clean Code

Avoid having Packages and Classes in same folder

Prefer Immutable over Mutable

Prefer Stateless over Stateful

Coding Best Practices (how to code)

Avoid duplication

DRY: Don't Repeat Yourself

Use It or Lose It

YAGNI: You Ain't Gonna Need It

Insert Fixes As You Go

// FIXME :
comments throughout code as a breadcrumb reminder to fix something before you sign off the card/task

Avoid java.util.Date and Calendar

"The JDK classes Date and Calendar are very badly designed, have had numerous bugs and have odd performance effects"

Maintain field ordering

In order:
  • Public constants (public static final)
  • Private constnats (private static final)
  • Public fields (these should not exist at all)
  • Private fields

Maintain method ordering

Public methods first.

Coding Philosophies (how to think about code)

Code is a Liability