DirtyInformation

Style Guides are Failures

Style guides are great for aesthetics, but fall short for what teams really need. Your team, future you, and the next developer to join your team thrive on communication of intention, and not the color of your brush.

The issues with a style guide start with the name that generates a certain intention. Style makes the style guide sound more like a personal touch. It is more about appearances than communication. The style guide is there to let you know what color paint to use and how wide the brush. It is more of a micromanaging arrangement where you are given what the ending should look like, but you don’t know what the painting is trying to say. This personal touch of a style guide leads to teams arguing over what is the best way to do X. The arguments are all about personal feelings. There is a place for this, but a change of direction might reduce the fights and increase communication.

Often a change in thought comes with a change in vocabulary. If the intention of the guide is to communicate then let’s start by replacing style with communication. The easy part is over.

Next, it is time to go through our old style guide and start asking ourselves “why?” Each decision that can be done in multiple ways needs to have a communicating reason that doesn’t reach into what the code looks like. Looks are important, but your choices need to allow the code to communicate more. Let’s take an example from the Ruby world.

  #Style Guide
  #blocks

  #single line blocks
  method { |foo| ... }

  #multi line blocks
  method do |foo|
    ...
    ...
  end

The “why” here is based on looks, and not on communicating intention or anything else. The hardest thing to communicate is intention. We are communicating the number of lines, but that should be pretty clear by counting. This also introduces incidental change when we find out we need to add another line. So what can we do better? I’m going to reach back to the great Jim Weirich for this example.

  #Communication Guide
  #blocks

  #functional blocks of code
  config = File.open("config.yml") { |file|
    YAML.load(file)
  }

  #procedural blocks of code
  File.open("foo.txt") do |file|
    file.write("data")
  end

  #in specs
  #setup blocks
  before {
    #...
  }

  #specifications
  specify do
    #...
  end

Jim was great about making communication more significant than aesthetics without losing the appeal of the viewer. Another example is his use of fail vs. raise.

Let’s all take a lesson from Jim and spend sometime asking “why” when we make decisions to have a certain style in our code. Squeeze every drop of intention out of every character your language allows. Are there any others you can think of?

The Past

• Testing Named Agents 03 Feb 2017
• Two Duplication Refactorings in Elixir 18 Jan 2017
• B is for BigDecimal 24 Sep 2014
• A is for Abbrev 02 Sep 2014
• Missed Chances 15 Aug 2014
• Style Guides are Failures 15 Jun 2014
• What is BDD anyway? 15 Apr 2014
• An Agile Contract 31 Mar 2014
• What Do I Want 23 Mar 2014
• Just the Tip 16 Mar 2014
• Important Partnerships 11 Mar 2014
• Lost in Translation 03 Mar 2014
• Story Splitting Revisited 23 Feb 2014
• Let your yes be yes and your no be no 16 Feb 2014
• Lethal Injection 09 Feb 2014
• Smaller is Better 02 Feb 2014
• A Second Time 26 Jan 2014
• Introspective 20 Jan 2014
• Self Reflection for the Win 06 Dec 2013
• Why? Why? Why? 30 Sep 2013
• A New Gig 18 Sep 2013
• Exceptional Comments 15 Jun 2013
• Role Objects in Acceptance Tests 30 Apr 2013
• Open Closed Ruby Woes 28 Apr 2013
• Write Something 12 Apr 2013
• A Great Cast of Characters 06 Mar 2012
• When is the Release Party? 19 Aug 2011
• Single Responsibilty, How Did I Forget You 12 Apr 2011
• Change Classes not Styles 05 Nov 2010
• My MongoDB Cookbook Recipe 20 Jul 2010
• Agile Says What? 05 Nov 2009
• Inject & Me - BFFs 07 Sep 2008