Creeping Inconsistencies

November 07, 2012

Why is it done like this over here, but like that over there?

- Every programmer, ever

Inconsistency costs development teams time in a number of ways.

  1. prompting questions of needlessly-differing approaches
  2. spurring technical debt cards to be written
  3. creating meetings for technical debt prioritization
  4. requiring huddles for effort estimation solutions

For architectural debt, and overarching concerns, creating cards and prioritizing them are effective. My experience with smaller items — such as enforcing a particular return style from JavaScript functions — is the opposite. Consistency is in the best interest of everyone, and is best enforced by an aggressive developer simply doing it.

Returning Inconsistencies

While working in our front-end code, I noticed we had a 60/40 split in the way we returned from our JavaScript view models.

var self = {};
self.shippingModeOptions = ['Sea', 'Rail', 'Truck'];

// ---

return self;

// vs

return {
    shippingModeOptions: ['Sea', 'Rail', 'Truck']

My process for dealing with this type of inconsistency is two-fold.

First, determine the differing ways we’re accomplishing the same thing — I found the two above.

Next, decide which is better. I prefer the second style for a couple reasons.

  • Everything this function returns is together
  • It’s succinct

Library Usage

We’ve been using the excellent KnockoutJS library since long before the 2.0 version, but we’ve also been quick to upgrade to new releases. Just like you’d expect for a major release, KnockoutJS 2.0 came with some API changes. We had an 80/20 split in the way we create dependentObservables.

var title = ko.observable('Mr.');
var firstName = ko.observable('Ellis');
var lastName = ko.observable('Dewald');

// ---

var fullName = ko.dependentObservable(function(){
    return [firstName(),lastName()].join(' ');

// vs

var formalName = ko.computed(function() {
    return [title(),firstName(),lastName()].join(' ');

In KnockoutJS 2.0, ko.dependentObservable was renamed to the more terse ko.computed. This is problematic for a few reasons.

  1. You’d have to be reading the KnockoutJS computed documentation to find out what a dependentObservable is
  2. It’s reasonable to expect that these two differently-named functions do different things, which again takes time in the form of questions, explanations, and googling.

The point is not to create an atmosphere where questions shouldn’t be asked — they’re a critical part of the success and cohesion of any team. The point is to spare the team from spending time on low-value questions. Quashing the existence of two equivalent, but competing, styles is a great way to ease the transition of new folks and encourage time is being spent on those high-value questions and conversations.

Profile picture

Written by @sghill, who works on build, automated change, and continuous integration systems.