Coding principles, designs, and styles

Overarching Principles

  • Care about quality. Care about code quality, design quality, and user experience. Strive for excellence.
  • Lets build something that we can be truly proud of. A product that gives us a great reputation.
  • Readability and maintainability are of primary importance. Don’t be clever, instead be clear. Don’t be sloppy.
  • Use source-level comments generously to document the design. Comment each class, method, and “logical steps” within methods. What you are striving to document is the “Why?” and “How?” questions.
  • Test early, test often.
  • Thou shall not make hard to use classes/modules. Pull complexity into a class, rather than pushing it onto the user of the class. Make interfaces brain-dead simple to understand and use.

Bread and Butter

  • Strive to make code naturally readable via class, method, and variable names. This is in addition to good commenting.
  • Use a consistent code style within the app. Use the dominant style within a file.
  • Write production quality code. Don’t assume you’ll have time sometime later to clean it up.
  • Don’t check in code that has warnings. Resolve them.
  • Make changes in small incremental steps. When a step is stable/complete, check it in your local git clone. Push the local checkins to the repo when they are production quality — strive for daily pushes. The goal here is to keep everyone in sync, but without breaking things.
  • Add “TODO:” comments to document work that has been temporarily skipped.
  • Don’t duplicate code. If you ever find yourself copying a chunk of code, pasting it and then making a few minor changes. Stop, refactor, and parameterise the differences.
  • Methods should be small. Use this as a general principle, don’t abuse it. It’s fine for a method to be large, if it should be.
  • Never put domain-specific logic within a general purpose class. E.g. you shouldn’t have a general dialog class do something like, “if (fromActivity instanceOf BooActivity) {}”.
  • Strive to use the “Locality Principle” — group related code (classes, methods, blocks within methods, and variables) together. This also applies to delegate/call-back interfaces. It is better to use anonymous classes (declared at the point of use) rather than declaring the interface in the class definition — don’t do this: public class FooActivity extends BaseActivity implements VerticalPager.OnScrollListener.

This or That, But Let’s Do It This Way

  • Use 4 spaces rather than tabs.
  • Use whitespace and comments to make “logical steps” stand out. In the same vain, put scope brackets “{“, “}” on their own lines. Vertical whitespace is not your enemy.
  • use camelCase for variable and method names. “Upper camelCase” for Class names. Lowercase for package names.
  • Start member variables with an “m” — mMemberVariable.
  • Start static variables with an “s” — sStaticVariable.
  • Use scope brackets even for single line ifs, for-loops, while-loops, etc. Its just too easy to mess up the scoping of these statements. The brackets also make the blocks stand out better.