The Pebble Way

“Simple software that solves difficult problems”
— pebble {code} website (2012)

This document, “The Pebble Way”, is the culmination of our collective wisdom in software development. It is designed to drive discussion; to create a positive and proactive culture.

New Developers

Watch the “Simple Made Easy”¹ video, as this was the original inspiration for many of the principals added to this document. We hope that this will inspire you, as it did us, to strive to create “simple” software solutions.

On-going Use of The Pebble Way

Having read the guidelines, the challenge is to put these into practice in our day-to-day software development.

This document will evolve over time; at any point a team member can suggest a change, and if the team agrees then the change is adopted.

The Guidelines

What follows are some guidelines under the folowing headings:

• General
• Requirements
• Design
• Review
• Implementation
• Documentation
• Testing
• Build/Deployment

These headings are only there to make it easier to navigate the content: they do not imply that we are following a waterfall process.

The guidelines have been further categorised
(idea stolen from Framework Design Guidelines) into:

• Do
  • Something that we feel is extremely important to do.
  • There will only be very rare exceptions, and these need to be discussed by the whole project team.
• Consider
  • Something that is our default approach, but we sometimes choose not to do when we understand the implications.
  • These exceptions must be discussed in an early review.
• Avoid
  • Something that we try not to do, but may sometimes choose to when we understand the implications.
  • These exceptions must be discussed in an early review.
• Don’t
  • Something that we feel is extremely bad practice.
  • There will only be very rare exceptions, and these need to be discussed by the whole project team.

General

• DO
  • Use simplicity as the primary metric when evaluating competing options
• CONSIDER
  • Automating repetitive tasks
• AVOID
  • Complex solutions
    • Only ignore this recommendation if the benefits are demonstrably overwhelming
• DON’T
  • Repeat yourself!
  • Fix it if it ain’t broke
    • We only refactor code that we are actively working on, otherwise we live with the imperfections and tackle higher priority issues.

Requirements

• DO
  • Ensure that acceptance criteria are clearly identified before starting work on a story
• CONSIDER
• AVOID
• DON’T

Design

• DO
  • Follow SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) design principles
• CONSIDER
  • Pursuing a functional approach – immutable types, pure functions etc
  • Asking for a design review at any point of working on a story
    • Feel free to pair with another developer if that seems like a better way to get two heads involved.
• AVOID
  • Constructing invalid objects
  • Mutable objects
• DON’T

Review

• DO
  • Get a code review when you think you’ve finished implementation
  • Guide reviews using SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) principles
• CONSIDER
  • Starting reviews from the unit tests
    • Lack of unit tests is an immediate failure of the review
    • A reviewer should be able to infer the single responsibility of a class from the test suite
• AVOID
• DON’T
  • Be fooled by self explanatory easy to read code – it isn’t necessarily SOLID

Documentation

• DO
  • Write self explanatory code
  • Write readable unit tests
  • Document all major design decisions – one possible approach:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
  • Add a single sentence XML code comment to the top of classes you write or touch
    • Being forced to describe the single responsibility of a class can be a useful design aid
  • Add a project level README.md to explain the role of each project within the solution
  • Add one or more high level diagrams to explain the big picture
• CONSIDER
• AVOID
• DON’T

Testing

• DO
  • Use unit tests as your primary test mechanism
  • Cover non-core code including build and view models
  • Use clear and understandable naming of tests
• CONSIDER
  • Adding smoketests to validate components
• AVOID
  • Extensive usage of stubs and mocks in unit test setup
• DON’T
  • Test multiple scenarios in a single unit test

Build/Deploy

• DO
  • Keep the build green at all costs
    • Panic when the build goes red – establish who is working to resolve the issue
    • Prioritise fixing the build over finishing a story
  • Treat build/deploy scripts as first class citizens
    • The same rules and standards you apply to code apply to your scripts
• CONSIDER
  • Backing out changes that break the build
• AVOID
• DON’T
  • Disable any automated tests

References/Further Reading

¹ Simple Made Easy:http://www.infoq.com/presentations/Simple-Made-Easy-QCon-London-2012

² Code as Design:http://www.developerdotstar.com/mag/articles/reeves_design_main.html

³ Framework Design Guidelines:http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613

⁴ Architecture Decision Records:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

⁵ SOLID::http://en.wikipedia.org/wiki/SOLID_(object-oriented_design)

⁶ Immutable Types:http://msdn.microsoft.com/en-us/library/hh297115(v=vs.100).aspx

⁷ Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx