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:

• http://docs.codehaus.org/display/PICO/Good+Citizen
• http://www.assembla.com/wiki/show/burro/Development_Principles
• http://www.ivanism.com/Articles/AgileXPSoftwareDevelopmen.html
• http://www.architech.ca/2010/03/agile-development-9-rules-to-live-by/

Build/Integration

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)

• Commit Often: http://www.codinghorror.com/blog/2008/08/check-in-early-check-in-often.html
• Don't Go Dark: http://www.codinghorror.com/blog/2008/06/dont-go-dark.html
• Revert often: http://stackoverflow.com/questions/1286057/continuous-builds-and-agile-vs-commit-often/1286126#1286126

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

Fast Builds

Testing

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 http://www.xprogramming.com/Practices/PracOwnership.html

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 http://www.xprogramming.com/Practices/PracCodingStandards.html

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

See:

• http://qconlondon.com/london-2009/presentation/Null+References:+The+Billion+Dollar+Mistake
• http://andyp-tw.blogspot.com/2008/08/returning-null-considered-dishonest.html
• http://en.wikipedia.org/wiki/Null_object
• http://martinfowler.com/eaaCatalog/specialCase.html
• Chapter 7: "Error Handling" of Clean Code

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
http://codeliability.blogspot.com/2007/07/statics-are-evil.html

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

• See Why getter and setter methods are evil
• and More on getters and setters

Prefer Stateless over Stateful

Coding Best Practices (how to code)

Avoid duplication

DRY: Don't Repeat Yourself
http://en.wikipedia.org/wiki/Don%27t_repeat_yourselfhttp://c2.com/cgi/wiki?DontRepeatYourself
http://www.redhillconsulting.com.au/products/simian/
http://pmd.sourceforge.net/cpd.html

Use It or Lose It

YAGNI: You Ain't Gonna Need It
http://en.wikipedia.org/wiki/You_ain%27t_gonna_need_it
http://www.xprogramming.com/Practices/PracNotNeed.html
http://c2.com/xp/YouArentGonnaNeedIt.html

Insert Fixes As You Go

Use

// 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