Who am I?

I’m an Agilist, a former software engineer, a gamer, an improviser, a podcaster emeritus, and a wine lover. Learn more.

Currently Consuming
  • The Lean Startup: How Today's Entrepreneurs Use Continuous Innovation to Create Radically Successful Businesses
    The Lean Startup: How Today's Entrepreneurs Use Continuous Innovation to Create Radically Successful Businesses
    by Eric Ries
  • The Talent Code: Greatness Isn't Born. It's Grown. Here's How.
    The Talent Code: Greatness Isn't Born. It's Grown. Here's How.
    by Daniel Coyle
  • Alexander Hamilton
    Alexander Hamilton
    by Ron Chernow
« Link Roundup for 21 May 2011 | Main | Sign Me Up for Alchemy »
Thursday
May192011

Because I am Clearly an Expert on Style 

Rob Donoghue asks:

How critical is a unified style/formatting guide for developers in an agile environment? On one hand, the common formatting would seem to help the hand-off, but on the other it seems it might be seen as an unnecessary limitation.

My first instinct is to say, “Not at all. You’re pair-programming enough that the style comes reflexively, rather than being prescribed by a document.” Given that I’ve just been working on the coding standards document for our teams, however, I realize that’s not always as true as I want it to be.

What it works out to is that you have to document what you can’t talk about. We’ve got three teams split across four different locations, so we have to rely on documentation as a replacement for conversations more than we would like. We do try to write just enough to put the right ideas in people’s heads, and nothing more. Documentation can’t substitute for judgment. It can tell people what to worry about. Here’s how our coding standards start:

At a high level, we want to embody these concepts:
* Correctness, simplicity, and clarity come first
* Do not prematurely optimize
* Do not prematurely pessimize
* Hide information
* Give each entity one cohesive responsibility
* Ensure resources have owners
* The compiler is your friend

We maintain this on wiki page; each of those bulleted points links to a page with more detailed information about specific ways we try to enact the principle.

A lot of my thinking about this has been influenced by Ron Jeffries’ Card-Conversation-Confirmation model for user stories and the Agile in a Flash cards (whose authors also have something to say about coding standards). What is written is a spur to have a conversation, so write only enough to get people talking about the right things.




Update

Fitness: Ran 2.25 miles + 30 minute workout
Writing: 383 words, 267 average

Reader Comments

There are no comments for this journal entry. To create a new comment, use the form below.

PostPost a New Comment

Enter your information below to add a new comment.

My response is on my own website »
Author Email (optional):
Author URL (optional):
Post:
 
Some HTML allowed: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <code> <em> <i> <strike> <strong>