But, it’s not just the content - the code itself - that affects readability. How it’s presented matters and if we’re going to talk about presentation, we have to talk about typography.

One could argue that, all things being equal, source code should be written in a way optimized for reading. Sure, occasional performance concerns require putting readability in the backseat, but this is rare. Source code should be written to be understood by people.

This isn’t a radical concept, and it’s why we have structured programming, why we use descriptive variable names, and why we have conventions about where the files containing source code live. If a codebase is like a book, we’re all agreed how to title the chapters, where the table of contents should go, and what the index looks like.

But there’s also how the code is presented to us - the code’s typography. Typography is, according to Wikipedia, “the art and technique of arranging type in order to make language visible.” Type of course, is the presented text, so typography, then, answers the question “what does each letter look like, and where does it go?”

We use typography all the time in our code. We indent it whenever a new scope is created. We limit our line lengths to a certain number of characters. We color-code bits of code according to their purpose, aka syntax highlighting. Some of us even align other parts of our code, such repeated inline comments, like so:

1
2

int left = shape.positionLeft(); // Our display is left-oriented
int top = shape.positionTop();   // We start drawing pixels from the top

This sort of “code formatting” isn’t about correctness, it’s about aesthetics, all in aid of making the code easier to read. Typography doesn’t address what should be written but rather how it should be presented to make what was written as readable as possible.

A designer friend recommended “The Elements of Typographic Style”, by Robert Bringhurst. This is “The Art of Computer Programming” for typography. Very early in the book, Bringhurst has this to say:

Well-chosen words deserve well-chosen letters; these in turn deserve to be set with affection, intelligence, knowledge and skill. Typography is a link, and as it ought, as a matter of honor, courtesy and pure delight, to be as strong as others in the chain.

This is a passion for “fonts and stuff” that I never knew existed. But, he’s right. A well-typeset book is a leisurely stroll on a spring day, while a poorly set document is an encumbered march through a muddy field on a rainy day.

If you are at all interested in typography, typesetting, or fonts, I highly recommend the book. It’s easily read, well-written, and - of course - beautifully typeset.

In the book, he talks about font choices, line heights, kerning, alignment, grids, tables, and anything else you could possibly imagine needing to make a design decision about when putting words onto a page. But, it’s all about prose. Can we apply any of these lessons to source code?

We’ve already established that programmers generally get value out of typography, via indentation and whitespace. Many of us have a favorite fixed-width font for editing, and we can all argue about what the proper length of a line of code should be.

Some languages, like CoffeeScript and Python, require adherence to certain typographic principles - you must indent new blocks of scope. The Go language comes bundled with its own typesetting program: gofmt. Thus, all Go programs adhere to a strict set of typographic principles. There’s a certain logic to this.

Is indenting and color-coding our source enough? Can we make our code even more readable by heavier use of typography?

Let’s find out.

We’ll start with C, one of the oldest “high-level” languages. Here is the source code for the strcpy function from the BSD kernel:

1
2
3
4
5
6
7
8
9
10

char *
strcpy(to, from)
        register char *to;
        register const char *from;
{
        char *save = to;

        for (; (*to = *from) != 0; ++from, ++to);
        return(save);
}

It’s a short routine that packs a lot of functionality. It’s set according to the BSD guidelines, with an 8-character indent (likely a tab). Other than that, there’s not much going on typographically. Does this make it hard to read? Can we make it easier to read without changing the code?

Let’s start with the function declaration. I like how the return type (line 1) is on a different line than the function and argument names (line 2), as it breaks up the signature into different chunks. The argument declarations themselves (lines 3 and 4), which each appear on their own line after the function name, could be better set, in my opinion.

A C argument declaration is made up of modifiers (register, const), a data type (char *), and a name (from). In this case, the elements of each declaration are vertically aligned, but in an odd way (likely their alignment is merely by happenstance - both arguments are declared register). The char for the argument to aligns with the const of the argument from. const is a modifier, and char is a data type. Things that are different are aligned with each other, which implies a sameness that doesn’t exist.

Let’s re-set the argument list, aligning like with like, forming a table structure, like so:

1
2
3
4

char *
strcpy(to, from)
        register       char* to;
        register const char* from;

Now, the arguments block forms a table of three columns. The modifiers make up the first column, the data types are aligned in the second column, and the names are in the third column (also notice how the syntax highlighting reinforces the new table structure). We’ve also re-set the data type such that there is no space between char and * - the data type of both of these variables is “pointer to char”, so it makes more sense to put the space before the argument name, not in the middle the data type’s name.

Let’s move onto the for loop. I’ve always found the for loop in C to be an odd construct, and it squeezes quite a bit of functionality into a small space. It has two parts: the loop declaration and the loop body. The declaration itself has three sub-parts: an initializing section, a test to see if the loop should continue, and code to run each time through the loop (the body is also executed each time through the loop, which is one reason I find this construct strage).

This particular for loop is tricky, because there is no initializing code in the declaration, nor is there a loop body. To make this loop easier to read, we could rewrite it, but typography isn’t about changing the words, it’s about honoring them and making them easier to understand. Can we re-set this code without changing it, but make it more readable?

One thing that would be handy is to make it more clear that there is intentionally no initializing code nor loop body. We’d also like to make it simpler to see each part of the for loop for what it is. Let’s add some whitespace and vertical alignment to see if we can improve it.

1
2
3
4
5
6

for (
                          ;
        (*to = *from) != 0;
        ++from, ++to
    )
    ;

By vertically aligning the semi-colons, the missing initializer jumps right out at you. The whitespace created by the semicolons now looks intentional - that space couldn’t be there by accident. We’ve done the same with the loop body, although we took care not to vertically align that semi-colon, thus creating a visual distinction between the two parts of the for loop.

With regard to the intentionally missing elements, developers might reveal this intent via a comment, like /* no-op */. What I find interesting is that we can do this with mere typography. The reader feels the intention without being directly told.

Let’s look at another example, this time using a much more recent programming language: Ruby. Ruby takes its syntactic cues from Smalltalk and relies much less on analphabetic characters like braces and parens. It also supports a powerful literal syntax for arrays and hash tables. You can’t read too much Ruby code before coming across a Hash literal.

Let’s look at the routine from Ruby on Rails for creating a text field tag in HTML:

1
2
3

def text_field_tag(name, value = nil, options = {})
  tag :input, { :type => "text", :name => name, :id => sanitize_to_id(name), :value => value }.update(options.stringify_keys)
end

Wow, that is way off the page (or wrapping horribly, depending on how you’re reading this).

An important role that typography plays is to establish a “rhythm” to the typeset prose. In a book, this means making decisions about font size, margins, line lengths, and so on. The idea is to set each line long enough to let the reader take it in, but not so long that the reader becomes exhausted or loses their place. This code has no rhythm and is exhausting to read.

Compounding the problem of overall length is that the information here is at varying levels of abstraction. We have a method call to tag, some symbols, a Hash, and more method calls at the end. By the time you get to the end of this line, it’s hard to remember what it’s even supposed to be doing. We need to break this up with some sort of rhythm that will allow us to process it in chunks.

In English, we would establish this rhythm by analyzing the length of words and sentences. In source code, we have tokens and expressions. This Ruby method has 29 tokens, all on one line. That line has several expressions as well, and both of these facts are what’s making this line so hard to read.

Let’s re-set this code to keep the tokens-per-line low but avoid splitting expressions across lines.

1
2
3
4
5
6
7
8
9
10
11

def text_field_tag(name, value = nil, options = {})
  tag :input,
      {

        :type  => "text",
        :name  => name,
        :id    => sanitize_to_id(name),
        :value => value

      }.update(options.stringify_keys)
end

Each line now has only one or two expressions, and many fewer tokens. We’ve also used indentation and whitespace to delineate each part of this code.

Both arguments to tag are left-aligned at the seventh column - similar things have similar alignment. The biggest change, however, is in the Hash literal.

First, we’ve offset its contents by whitespace, primarily to distinguish it from the call to the update method. Without a blank line after the final value in the Hash, there’s an unfortunate vertical alignment between the hash key :value and the method call to update. We want to make it clear that these are distinct, and want to keep the reader from getting confused.

The Hash contents themselves have been re-formatted to form a visual table. We’ve used the “hashrockets” as a dividing line between key and value, which results in both being vertically left-aligned.

The code now has more of a rhythm to it, and can be read more easily, with line breaks inserted to give the reader a rest at the appropriate times.

Before we finish, I’d like to examine a typographical convention I’ve seen in JavaScript code, and discuss why I believe it actually impairs readability, failing to honor the content and thus fail to help the reader.

The convention was born out of a common idiom in in JavaScript where variables are declared in a comma-delimited list after a single var, with the list terminated by a semicolon. The typographical convention I’m referring to is in how this list is formatted, namely, it’s formatted with leading commas, like so:

1
2
3
4

var x = shape.left()
  , y = shape.right()
  , numSides = shape.sides()
  ;

This is typeset poorly, insomuch as it does not honor the readability of the content, instead hindering it.

The most important part of a variable declaration is the name of the variable (the second being its default value). Putting a comma first creates at typographic roadblock between the reader and the information they need (the variable name). That a comma is required between variable declarations is one of the least important pieces of information in this code, yet it’s front and center. This is bad typography.

The more conventional approach is much better, as the language’s peculiarities simply fade away:

1
2
3

var x = shape.left(),
    y = shape.right(),
    numSides = shape.sides();

Each line can now be easily read from left to right. The var establishes this block as a “paragraph”, and each declaration is a sentence. Each line is eminently readable - it starts with the name of the variable, which is what the reader is most interested in, and is followed by the default value. The names are left-aligned and are the first thing on each line (save for the initial var which establishes that these are variables). The commas, being incidental, are hidden nicely at the end of the line.

We can reinforce this structure with vertical alignment of the =:

1
2
3

var x        = shape.left(),
    y        = shape.right(),
    numSides = shape.sides();

We could go even further and align the commas and semi-colon, however this draws attention to aspects of the code that aren’t important (much as the comma-first style does). Although JavaScript needs to know when each declaration ends, we, the human reader, already know - the line merely ends. The declaration block itself ends with whitespace - that JavaScript requires a semicolon is incidental to reading this code.

This is why the “comma-first” typesetting is so distracting. It puts the comma - something unimportant to reading the code - right up front, forcing the reader to slog through it to get to the real meat of the declaration.

I could go on about many more idiomatic typesetting in various languages, but I thought it would be a fun exercise to make an argument against this style, based purely on tyopgraphical concerns, and see if it sticks.

Thinking about code typography has made more more bold in my code formatting choices, but there is a practical cost to this: source control diffs.

Unlike a printed book, code changes frequently. When we use heavier typography, we end up having to re-set the code around a particular change, and this creates non-functional changes to source code, making the overall changeset larger than it needs to be. I suppose we’d have to start applying typographic principles to our diffs as well :)

Despite these problems, I still think it’s worth taking a fresh look at code typography - anything that helps us read and understand code better has to be a good thing. At the very least, having a clear understanding of why code is set in a certain way can help us better understand the purpose of the code, and the trade-offs we make between reading, modifying, and writing it.

Special thanks to @mrmrs_ for the book recommendation and to @jxblk for reviewing this post.

One thing Heroku doesn’t provide out of the box is a login system for “internal” users. The vast majority of the software at Stitch Fix is targeted at Stitch Fix employees - to operate the warehouse, choose what goes into a fix, etc. The natural way to allow them to login is via Google Apps. We can use everyone’s existing username/password, and employees can be added during onboarding and removed when they leave the company, all in one place.

Getting it to work with our Rails apps seemed easy enough with OmniAuth, but it turned out to be a lot trickier, resulting in random failures with the oh-so-helpful error “invalid_credentials”. Here’s how to fix that, and why you can’t just use the out-of-box configurations recommend by OmniAuth.

tl;dr scroll down

This is not a dig at OmniAuth - it’s super awesome. It’s just that it bakes in a lot of assumptions that may not hold if you are using Heroku or are follow the 12-factor app architecture. You end up needing to know a bit more about how things are working, and you have to stop trusting default configurations.

First, the general setup of OmniAuth recommends this:

1
2
3

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :google_apps, domain: 'your-domain.com'
end

We use the omniauth-google-apps gem, which is a very thin extension of omniauth-openid that makes setup a bit simpler, and allows us to only allow Stitch Fix employees access to our systems.

This setup has issues with SSL certificates, so we need to tell OpenID where the CA file is, and we just use curl’s, checked-into our source code because of Wacky Heroku Thing #1 - no guarantees about what’s on the Dynos.

1
2
3
4
5

require 'openid/fetchers'
OpenID.fetcher.ca_file = File.join(Rails.root,'config','curl.pem')
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :google_apps, domain: 'your-domain.com'
end

We can’t just assume that curl is even installed, much less make any assumptions about where the pem file is, so we have to include it. Another option would be to provide an environment variable based on where we know it is on the Dyno, but this seemed simpler.

Now, the problem with this setup vis-a-vis Heroku is that there’s a configuration option being set that is not apparent, because OmniAuth/OpenID is using what it believes to be a sensible default, but is, in fact, not correct.

OpenID requires the ability to store information server-side so that, after you are redirected back from the auth provider (Google, in our case), the server can find this information and complete the login. How this information is stored can be configured via the :store option to provider. The default is an in-memory store, so it’s equivalent to this:

1

provider :google_apps, domain: 'your-domain.com', store: OpenID::Store::Memory.new

For development, this seems reasonable - it doesn’t require any setup - but for deployment, it’s Just Wrong, which we can tell by reading the RubyDoc of the OpenID::Store::Memory class from ruby-openid:

1
2
3
4
5

# An in-memory implementation of Store.  This class is mainly used
# for testing, though it may be useful for long-running single
# process apps.  Note that this store is NOT thread-safe.
#
# You should probably be looking at OpenID::Store::Filesystem

We’ll get to OpenID::Store::Filesystem, but what’s wrong with the memory store?

Let’s assume Unicorn as the server (as recommended for the Cedar stack for Rails apps). The recommended configuration allows three unicorn processes per Dyno, which gives use three processes, each with it’s own separate memory space.

Because unicorn uses process-based concurrency, which means that, when a new process is started, it gets a copy of the parent’s memory, all three unicorns on a single Dyno do not share memory. Meaning if process 1 started the OpenID dance, but, after redirect, your request was handled by process 2, it doesn’t have the necessary information stored in memory. Boom! invalid_credentails error.

So, what about that filesystem-based one? OmniAuth’s docs do mention OpenID::Store::Filesystem, but it’s still wrong on Heroku. Why?

Here’s how we’d set up the filesystem-based store:

1
2
3

provider :google_apps,
         domain: 'your-domain.com',
         store: OpenID::Store::Filesystem.new(File.join(Rails.root,'tmp'))

We can’t even be guaranteed of /tmp existing, so we set up the store inside our Rails app. This configuration works great in development, because I’m running my server on one machine - all three Unicorn processes share the same data store.

If we deployed to Heroku using just one Dyno, this would work. However, the second we scale up our app to use more Dynos, the entire thing falls apart. Why?

Two reasons:

• filesystem is ephemeral - it could go away at any moment. Between redirects it’s possible (however unlikely) that the files go away.
• Dynos don’t share filesystems. Even if we could guarantee the filesystem would live forever, you still run the risk that your OpenID dance will be handled by two different Dynos, and thus: invalid_credentials.

This is especially nasty because you might run your app for quite a while on one Dyno, thinking things are working when, instead, you’re sitting on a ticking timebomb.

What we need as a centralized place to store this information, accessible to all Dynos and that persists across reboots. This brings us to the third option included with ruby-openid, which is OpenID::Store::Memcache.

Of course, we can’t just plop store: OpenID::Store::Memcache.new into our configuration. We first need to add memcache to our app, and then extract the needed connection parameters from the environment. We also need to provide a memcache client object.

On Heroku, they recommend Dalli - strongly - so I went with that. The interface that OpenID::Store::Memcache expects from the memcache client is supported by Dalli, so we’re off to the races:

1

$ heroku addons:add memcache

1

gem 'dalli'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

require 'openid/fetchers'
require 'openid/store/filesystem'
require 'openid/store/memcache'
require 'dalli'

OpenID.fetcher.ca_file = File.join(Rails.root,'config','curl.pem')

Rails.application.config.middleware.use OmniAuth::Builder do
  if Rails.env.staging? || Rails.env.production? || ENV['OPENID_STORE'] == 'memcache'
    # Locally, these env vars will be blank, and it will connect to the local memcached
    # client running on the standard port
    memcached_client = Dalli::Client.new(ENV['MEMCACHE_SERVERS'],
                                         :username => ENV['MEMCACHE_USERNAME'],
                                         :password => ENV['MEMCACHE_PASSWORD'])
    provider :google_apps, domain: 'your-domain.com',
                           store: OpenID::Store::Memcache.new(memcached_client)
  else
    provider :google_apps, domain: 'your-domain.com',
                           store: OpenID::Store::Filesystem.new(File.join(Rails.root,'tmp'))
  end
end

Whew! This setup doesn’t require memcache for development, but allows it as an option by setting the OPENID_STORE environment variable. Although the Dalli client claims to use the environment variables automatically, the code doesn’t indicate this to be true when there is a username and password, and I’m kindof prefering some explicit configuration after all this.

Now, no more “invalid_credentials” error!

The way Heroku makes us design our apps is a good thing, but it’s easy to forget it because many “beginner” scenarios seem to work even if we’ve configured things incorrectly. Anything this crucial to your application is worth your while understanding at a detail level how it works - at least orient yourself around the default configuration. And deploy to two Dynos as quickly as you can.

This is not what switching to Vim means, nor is it a good reason to switch.

The reason to switch to Vim is to work better. I realize “better” is subjective, but whatever way you define it is what it means - code faster, edit text more easily, automate your workflow, whatever.

As such, switching to Vim is to throw out your old editor (or plan to) and replace it with a different tool that works differently and is, hopefully, better. Stop asking for “a plugin that does XXX like Sublime Text does things”. If Sublime Text has a plugin for what you want, you don’t need Vim. Vim might very well have a plugin that does whatever XXX is, but it’s more likely that you don’t need a plugin, or that Vim provides a way to accomplish your real goal much more efficiently.

Here’s how to make the move.

First, you aren’t going to learn much Vim from this. There are tons of great tutorials about how to actually use Vim. You will, of course, need those to switch to Vim, but you’ll also need a bit of a plan. This is that plan.

1. Run stock at first.
2. Ease into it.
3. Learn to install and remove extensions.
4. Add configuration and extensions only when needed.

Run stock at first

Don’t install Janus. Don’t install someone’s dotfiles. Don’t install anything but Vim. Vim is hard enough to learn without dealing with someone else’s idea of a good editing environment. Remember, your goal is to edit text (and code) better. You’d be surprised at just how easy that is with a vanilla install of Vim and a bit of elbow grease.

It’s also important that, when learning Vim, you learn it from first principles. You need to know in your heart of hearts that Vim editing is all about combining movements with actions. It’s like playing a musical instrument.

To learn to play guitar, you should grab an acoustic and a chordbook. You should not get a Marshall half-stack, vintage pedalboard, and Gibson Custom Shop Les Paul Slash Special Signature Edition. In all honesty, you’re likely to find out a Fender Strat works just fine with a good distortion pedal, so don’t start off with a bunch of crap in your ~/.vim directory.

Ease into it

You don’t want to uninstall Chocolat (or whatever) and jump into your next coding assignment with Vim. At least not at first. That will be bad for you and your company. Instead, tell your operating system that henceforth, all text files, Markdown files, Asciidoc files and any other text-like format shall be edited in Vim. Then, proceed to use Vim only for editing text.

Although editing text doesn’t benefit from many of Vim’s amazing plugins and features, it requires just enough for you to “level up” and get better at editing text. Before you know it, you’ll be deleting words, moving the cursor with search, creating abbrevations and all the other great stuff that makes Vim Vim, but in a safe, easy environment of text editing. If you don’t edit a lot of text, shame on you. You should write more. It’s good for you.

Now, don’t just go into insert mode and cursor around like you’re in Notepad. This is where those tutorials and references come in. Follow them and use them. My advice is:

• When you get a thought down, hit escape to go to command mode¹. A.B.C. Always Be in Command Mode. A, Always, B, Be, C, in Command Mode. You enter command mode mode or you hit the bricks.
• When are ready to type, enter insert mode and type. Then hit escape when you are done. A.B.C.
• Before touching the mouse, the cursor keys, the backspace key, or the delete key, ask yourself what you are really trying to do. Are you really deleting 10 characters that are all adjacent to each other or are you deleting a word? Are you really moving down 12 lines or are you going to the next paragraph?
• Stop thinking about characters and lines. Think in words, sentences, paragraphs, tokens, blocks. You are learning the Weirding Way, here. Visualize where you want the cursor to go, and make it go there. If you repeated a keystroke to do it, try harder.

Eventually, you will start to discover things you want to improve about your setup. Almost always, they can be fixed by mapping new commands or adjusting configuration. The Vim help is truly amazing. Read it. Like a book.

On occasion, you will need more than what you can achieve with just mappings and configuration. This is when you might benefit from an extension. You need to know how to easily install (and remove) them.

Learn to install and remove extensions

I’m gonna get prescriptive here. Just do it this way, and when you get your brown belt, you can switch to something else. Install pathogen and use that to manage your Vim extensions. Why?

Your ~/.vim directory (as well as the system Vim directory) has a specific structure organized by a file’s meaning to Vim. For example, all syntax files go in one place, and all help files go in one place, etc. This means that installing extensions using stock Vim results in a smattering of files all over the place related by Vim function and not by semantic function. All the Ruby-related files are not in a directory called ruby. It’s not good, but you can’t expect a 30+ year old editor to have got everything right the first time.

Pathogen solves this by allowing each extension to have its own Vim-like directory structure completely separate from all others. This is just like a “bundle”-type system in more modern editors. This means you can easily add and remove extensions with just a few commands.

Here’s how to set it up:

1
2
3

> mkdir -p ~/.vim/autoload ~/.vim/bundle
> curl -Sso ~/.vim/autoload/pathogen.vim \
    https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim

Put this at the top of ~/.vimrc:

1
2
3

execute pathogen#infect()
syntax on
filetype plugin indent on

This gives you a system in which to manage extensions. Test it by doing this:

1
2
3

> cd ~/.vim/bundle
> git clone git://github.com/nanotech/jellybeans.vim.git jellybeans.vim
> vim some_file

Now, in Vim, do :colorscheme jellybeans and you should see your colors change (or at least you shouldn’t get an error).

Do not manage plugins by typing git commands. That was just a test. We’re here to improve things and the way you do that is with a command line app. When you pass the Jedi trials (or cut Darth Maul in half), you can do something fancier, but this at least keeps you from typing a bunch of git commands:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

#!/usr/bin/env ruby

require 'optparse'
require 'fileutils'
require 'open-uri'

options = {}

opts = OptionParser.new do |o|
  o.on("--clean","Delete everything before re-cloning") do
    options[:clean] = true
  end
end
opts.parse!

git_bundles = [
  "git://github.com/nanotech/jellybeans.vim.git",
  "git://github.com/tpope/Vim-vividchalk.git",
  # add more here
]

bundles_dir = File.join(File.dirname(__FILE__), "bundle")

FileUtils.cd(bundles_dir)

if options[:clean]
  puts "Trashing everything (lookout!)"
  Dir["*"].each do |d|
    FileUtils.rm_rf d
  end
end

git_bundles.each do |url|
  dir = url.split('/').last.sub(/\.git$/, '')
  if File.exists?(dir)
    puts "  Skipping #{dir}, as it already exists"
  else
    puts "  Unpacking #{url} into #{dir}"
    `git clone #{url} #{dir}`
    if $?.success?
      FileUtils.rm_rf(File.join(dir, ".git"))
    else
      STDERR.puts "Problem with #{url}"
    end
  end
end

I keep this file in update_bundles in my ~/.vim directory (which I keep in version control). Since this is an awesome command-line app, you can do ./update_bundles -h and get some help. Start off with ./update_bundles --clean. This will delete your one bundle and re-clone it, along with a second bundle. That’s the “vividchalk” colorscheme, which I’m not recommending per se, but it’s just a second thing you can use to check that you’ve got everything set up properly. Do that via :colorscheme vividchalk.

To add extensions, place them inside the git_bundles hash and run ./update_bundles. To remove extensions, remove them from that hash and delete their cloned directory in ~/.vim/bundle. That’s it.

Of course, with great power, comes great responsibility…to not junk up your bundles directory with a bunch of stupid plugins you really don’t need to write code better.

Add extensions only when needed

I’m not saying you shouldn’t experiment and explore, but you will get the most benefit from Vim by not installing plugins that re-create features of the degenerate editor you are trying to get away from. You’re leaving it for a reason. Install plugins to solve editing and workflow problems you can’t get around with what vim gives you.

For example, a lot of people install NERDTree because they like seeing the world’s most difficult-to-use tree control from Windows Explorer right there in ASCII-art form in Vim. It turns out that controls like this were designed for locating files in a directory structure using a mouse on Windows 95.

If you think you need this plugin, you may not have thought deeply about the problem you are facing. Your problem is likely not “I need to navigate my project by tree structure and have it constantly there always even though I spend most of my time reading and writing particular code files”. Your problem is “I need to open a particular file more easily”. Vim has many ways to do that that are far better.

The most degenerate way is to do :e . which brings up a file navigator in the current directory. You can navigate the file system with Vim, which is great, but this is still not very efficient. A better way is to read about gf or :find, or look into the CommandT extension. All of these allow you to quickly find a file by name or path just by typing. Typing is fast as hell.

This is just an example, and it’s meant to illustrate that you should install extensions to solve problems, not to replicate features of other editors. Sometimes they will be same, but often they will not be.

To find plugins, search GitHub. Do not use Google, use GitHub. If you find a plugin that you cannot install by having update_bundles clone it into your .vim/bundle directory, you might not be searching GitHub. Or, you have a found a plugin that isn’t being maintained and you should avoid using it. Or, you should clone it to GitHub and start maintaining it.

As you get more comfortable, start using Vim for coding. It will be painful, but at least you’ll know how to navigate the project, copy & paste, and have some grasp of what’s going, thanks to the grounding in first principles you got while editing plain text files.

Find the plugin for the programming language you are using. Read the help to see what it offers and, if it looks useful, install it. You’ll likely want it just to get the syntax highlighting and indentation stuff working.

Finally, share what you’ve learned with other Vim users. Especially if they know more Vim than you. Those conversations will go like this:

• You: “Hey, did you know about #? It searches backward for the word under the cursor!!”
• Vim Master: “Yes! I love that command. Do you know about ?? It repeats your last search backward. n does the same forward!”

And then you learn something. On occasion, the Vim grand master will learn something from you. Vim just keeps on giving. It’s like that. Vim users are never short of a few tips to share, and as smug as they are around Emacs users, and as arrogant as they are around IDE users, they will be super-kind to anyone learning Vim.

So, go forth and switch! Run stock, then ease into it, then learn about pathogen, and then start leveling up. The next time you find yourself in Microsoft Word staring at a row of j’s, you’ll know you’ve made the switch.

Don’t get me wrong, I do do that, but only when the code is working according to my tests. Or, when I have to write JavaScript.

At my current job, I’m doing a lot more front-end than I had been, and so more JavaScript. The app I’m working on is a Rails app, and so I looked into the current state of the art with testing JavaScript.

In can be done, and it’s painful.

I have a few constraints or requirements for testing:

• I want to write CoffeeScript. Every time I have to type function() { } is a part of my life I won’t get back.
• I want the tests to run from rake without having to open a browser or navigate to some magic page that happens to run tests.
• I want to test every bit of logic I can, including logic involving JQuery. Basically, I want to know from my tests if the JavaScript code has broken.

The tools exist to do all of this, however they are amazingly degenerate compared to what was available in Java 10 years ago. We’ll get to that.

Jasmine

The current state-of-the art seems to be Jasmine. Our Rails app uses RSpec, and Jasmine is very much along those lines. You write your “spec” and then call assertions in the form expect(foo).toBe(bar):

1
2
3
4
5
6

describe 'my math library', ->
  describe 'can add', ->
    it "should handle 0", ->
      expect(SuperMath.add(9,0)).toBe(9)
    it "can handle negatives", ->
      expect(SuperMath.add(9,-5)).toBe(4)

Wonderful! There’s lots of useful matchers and, with CoffeeScript, the code is pretty readable. The output is very RSpec-like.

The first step to get this working is jasmine-rails. Jasmine-rails is mostly a wrapper around the Jasmine JS code, and a simple engine you can mount to run the tests in-browser.

1

gem 'jasmine-rails'

This will bootstrap a configuration file for you, and this is where the pain starts. The configuration is not well documented or well designed, so it’s hard to understand exactly where Jasmine is going to look for files. Further, Jasmine itself provides zero help when things don’t work. Basically, it just shows 0 specs and declares success. Add in the asset pipeline and if things don’t “just work”, it’s no fun.

I eventually got something working through trial and error. I would highly recommend starting with a spec that doesn’t require any of your actual JS files to work, e.g. expect(true).toBe(true) and so forth. Once that’s working, make assertions about the existence of your actual JS code before going ahead with real tests.

Painful setup is annoying, but it’s a one-time thing. Once I had this going, I needed to write some tests.

I have a feature where entering a number into a text field and hitting return causes certain behavior to happen on the page. If the number is “valid”, a radio button gets checked, and if it’s not, an error message gets shown.

Implementing this is pure JQuery, and I immediately felt frozen - how the heck am I gonna test this? Mock JQuery? And if I do, I’d just end up testing the implementation, e.g. “assert that JQuery called hide() on an element with selector ‘foo’” and so on. Not good.

Enter jasmine-jquery.

Fixtures with jasmine-jquery

Jasmine-jquery includes a bunch of matchers that help with JQuery-specific behavior, things like expect($("#whatever")).toBeHidden(). This is useful, but I’d still need to find some way to load up the page and execute the JQuery-based code on a DOM.

I could certainly do that in a Capybara test, but those are slow and flaky. I need a better way to control the markup that my JQuery executes on during a test.

A bit of code has inputs, which we arrange as part of our test, and we check the outputs of the code to see that it’s working. The fewer the inputs, the easier it is to test something. This is why functional programming is so appealing - functions tend to have fewer inputs than methods on an object (which have both their arguments and the internal state of the object as inputs). Well, JQuery-based JavaScript basically has “every piece of markup on the Internet” as its input.

Practically speaking, it has as input “all the markup on the page”, which is still a lot of inputs. I needed a way to both specify the inputs, but also to clearly document what parts of any page are the real inputs. Fixtures is a way to do that. Essentially, fixtures in jasmine-jquery are bits of HTML that will be available to JQuery as the DOM during your test.

At first, I attempted to place the fixtures in external files. This seems logical, but it requires the application to serve them up. Outside of the fact that our application requires authentication to every page, the headless version (below) just didn’t work at all when fixtures were in external files.

Carrying on the tradition of Jasmine and JavaScript in general, when things didn’t work, they just silently didn’t work, with no way of diagnosing what was going on.

So, inline fixtures it is. In other words, big strings of HTML.

First, we set up the spec:

1
2
3

describe 'returns', ->
  describe 'show', ->
    describe 'doing an item lookup', ->

Next, we set up our fixture in a beforeEach block using CoffeeScript’s handy multi-line string syntax. This keeps things fairly readable, despite the fact that we’re building a giant string of HTML:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

beforeEach ->
  fixture = """
  <div id="returns-fixture">
    <div id="flash-alert" class="alert" style="display: none;">
      <div class="msg"></div>
    </div>
    <div id="flash-notice" class="alert" style="display: none;">
      <div class="msg"></div>
    </div>
    <form id="item-id-lookup">
    <input type="text" id="item-id-field" name="item_id" autofocus="autofocus">

    <input id="item-1-in" type="radio" name="return[items][1][status]" value="In">
    <input id="item-1-out" type="radio" name="return[items][1][status]" value="Out">
    <input id="item-1-dmg" type="radio" name="return[items][1][status]" value="Damaged - Reparable">

    <input id="item-2-in" type="radio" name="return[items][2][status]" value="In">
    <input id="item-2-out" type="radio" name="return[items][2][status]" value="Out">
    <input id="item-2-dmg" type="radio" name="return[items][2][status]" value="Damaged - Reparable">
    </form>
  </div>
  """
  jasmine.getFixtures().set(fixture)
  window.StitchFix.controllers.returns.show()

(When editing this article,I noticed that Pygments highlighted the inline HTML. I wish Vim did that, it makes the fixture pretty readable!)

The second-to-last line instructs Jasmine to magically do some magic and make the HTML available to JQuery. I don’t know what part of this is Jasmine and what part is jasmine-jquery, but it works. The last line is some setup that gets called by our global JS for the particular page this JS is for.

This markup is somewhat duplicated from the actual ERB templates, but what can you do? If someone changed the ids on me, my tests will pass, but the app breaks. It’s all about compromise, and this seems like a decent compromise. These are unit tests, and I have to have some assumptions about the inputs.

1
2
3
4
5
6
7
8
9
10
11

describe 'should check the proper radio button when the id is submitted', ->
  beforeEach ->
    $("#item-id-field").val("1")

  it 'when there was no previous alert message', ->
    $("#item-id-lookup").submit()
    expect($("#item-1-in")).toBeChecked()
    expect($("#item-id-field")).toHaveValue("")
    waitForAnimations ->
      expect($("#flash-notice")).toBeVisible()
      expect($("#flash-notice .msg")).toHaveText("Item 1 marked as 'In'")

That last bit was really fun. We changed the hiding logic to do an animation. When we did that, our expectations fired before the animations had completed, making the test fail. So, we have to litter our test with this crud to get consistency. Here’s that function:

1
2
3

var waitForAnimations = function(andThen) {
  $(":animated").promise().done(andThen)
};

Yup, it’s in JavaScript, because a) I don’t know how to make global functions in CoffeeScript that works in this weird context of running tests and b) a class created here to hold the function wasn’t visible to my specs. I’m sure this is a CoffeeScript thing, but it’s still annoying.

But, things are working. Now, let’s get it running headless.

No browser was used in the execution of this test

Jasmine-rails includes jasmine-headless-webkit which, if you install QT properly on your Mac, will run these tests without a browser, on the command line, via rake, just like you’re supposed to in the 21st century. It even sets up the rake task: rake jasmine:headless. Not much of a name, but it works.

It’s slow, to be sure, but not nearly as slow as running it in the browser, plus it works on CI. The planets must be aligned inside my astrological sign.

It was a long, annoying trip to get here, but we finally have something sane to run tests in a pretty reasonable way, and I only had to type function() {} one time, we don’t have to mock JQuery and it’s all happening on the command line, where proper software development occurs.

Of course, all of this was done to code already written. I want to use my tests to drive the writing of code, and this is where the situation absolutely sucks.

Failure is the only option

One thing that’s super-important about writing tests first is watching the code fail in a specific way. If I call the method foobar, I want my test failure to be because that method doesn’t exist. This way, when the test does pass, I know that it had to correct affect on the codebase.

In some cases, this works OK. Let’s change our spec above to expect #item-id-field to have the value “foo”:

1

expect($("#item-id-field")).toHaveValue("foo")

The test failure message is very nice:

1
2

Expected '<input type="text" id="item-id-field" name="item_id" autofocus="autofocus">'
to have value 'foobar'. (line ~36)

The failure message is accurate, as is the line number. So far, so good.

Now, let’s introduce a typo. It happens, and, while annoying, is usually an easy problem to fix. Not in the world of JavaScript unit testing:

1
2

(/Users/davec/Projects/spectre/spec/javascripts/returns_spec.coffee:33)
   TypeError: 'undefined' is not a function

Umm, OK? I haven’t shown you where the typo is, and in a potentially large codebase, you might have a lot of code to look through. Let’s use the only information we were given and head to line 33 of our spec:

1

it 'when there was no previous alert message', ->

Not only is there no typo here, but this isn’t even the line of code that was executed that resulted in the error! Basically, at this point, we have two problems, one practical, and one more philosophical.

Practically speaking, we now have to just read through our source code looking for the typo. If we can’t see one, we have to start commenting out code until we get a different error message and then slowly comment it back in. In 2013. We put a man on the freakin’ moon in 1969, and JavaScript, the language of the web, has no stack traces. This is why we can’t have nice things.

On a philosophical level, it also means my ability to test-drive my JavaScript code is severely hampered. When starting out a new bit of code, I’m gonna have a lot of typos and unknown functions. With test failure messages that amount to “your code a splode”, it’s really hard to do that.

Want to see what the typo was?

1
2

notifications.close_noow("alert")
notifications.close_now("notice")

I fat-fingered the function close_now. So, not only did it not point me to any relevant line of code (and I’d be happy with the line of code in the generated JavaScript), it didn’t even tell me the name of the missing symbol.

Yes, yes, I know that what it was trying to do was execute a function call on the value "close_noow" from the notifications objects, which happened to be undefined. But, can’t we do better?

Interestingly, Google’s JavaScript runtime, V8, does a bit better, which isn’t surprising (thought it still boggles my mind that v8 has no readline support. You can’t even up arrow?!??!). But, installing therubyracer and instructing Jasmine to use it (or Node) as the JS runtime has no affect on the crappiness of this error message.

So, this is the state of things to my ability to find them. I hope I’ve missed something, but I fear I haven’t. Just piecing this together via various searches and form posts was tricky, which means that very few people are actually doing this in earnest.

It’s no wonder, because it’s a huge pain in the neck. I can only assume that I’ve created a ticking time-bomb in my application and, six months from now, it’s going to go off and CI will just fail constantly with “undefined is not a function” or something.

I don’t have a particular opinion on Node, but I can tell you that if developing Node is like this, I would never do it. This is no way to work.

Beneath what seems like a reasonable feature request lurks the heart of technological conservatism: what was and is always shall be.

(emphasis his).

I love everything about this, and it’s a helluva lot better than [Steve Yegge’s stinker][yegge].

Siracusa’s article inspires me in two ways:

• Stop holding “what I know” so dearly. “Lead or bleed”, as Chad Fowler says
• Stop accepting unjustified idioms & conventions as being “more correct”. “That’s just the way it’s done” is often the best explanation for doing things a particular way, but it’s not actually a legitimate reason for anything.

RSS is a huge part of my online life - every time I fire up Reeder and see stories, I get very happy. The way I use RSS (which I believe is the best way to use it) can’t be replaced by anything else that I’m aware of.

So, why do I think RSS is so great?

First, I don’t use RSS readers to “discover” anything - new blogs, what people are reading, etc. That’s what Twitter is for. When Google added that feature to Reader, it became really annoying to clear all that crap out.

Instead, I view my RSS feeds as a curated, frequently updated, bookshelf just for me. I have a list of carefully selected websites whose posts I want to read all of, on a daily (or more) basis. These websites conform to the type of reading I like - fewer, higher quality posts, as opposed to link-bait/page-view whores like Mashable or Engadget.

I’m not saying sites like Cinematical or Joystiq are worthless - there are some great posts on there, but Twitter is sufficient to alert me to them, and I’m rarely sad if I miss the few good posts out of the massive cruft on those sites (I mean, do I really care about how many megapixels are on Sony’s latest point-and-shoot, and do I really need a picture of the catering tray at the Arrested Development shoots?).

It’s a shame how these sites are run, because they do employ connected journalists who get real scoops and write great stories. But, their business models require a massive number of posts per day and so I just can’t trim the wheat from the chaff, so I don’t visit. Not sure if I’m alone in this.

So, what do I read? Here’s what’s in my RSS feeds. These are the sites I read daily and, because this is the 21st century, I don’t want to navigate to them one by one - I want software delivering them to me, and that’s what RSS, and a great client, do.

Comics

• Dilbert - duh
• Eye on Springfield - Screencaps from the Simpsons. Always brings a smile.
• Joy of Tech - Nerdy, Apple-related humor
• xkcd - double duh
• Thrillbent/Insufferable - Mark Waid is a genius.

Tech

• Coding Horror - classic programming blog (that, honestly, is not as good as it was).
• Daily WTF - duh.
• Daring Fireball - quality writing and analysis by John Gruber about Apple and related stuff. And plenty of snark.
• Marco.org - by the creator of Instapaper and The Magazine, it’s like Daring Fireball Lite but with a bit more variety.
• Michael Church’s blog (though I’ve skipped his recent nine treatises on workplace incompetence - he needs an editor).
• Signal vs. Noise - 37 Signals blog isn’t as great as it used to be, but still some interesting stuff.
• Github’s blog - Gotta keep up with one of the most amazing programmer tools ever made.
• Giles Bowkett’s blog - insightful posts about Rails and other stuff.

Funtimes

• Scott’s Blog of Doom - Pro Wrestling recaps and snark. Yes, I like Pro Wrestling and yes, I have a sense of humor about it.
• Wil Wheaton’s Blog - I came for his hilarious recaps of TNG episodes, I stay for his great writing, obsessive honesty and general awesomeness.
• Meeting Boy - daily quips from someone always stuck in a meeting.
• Clients from Hell - daily reminder of why I don’t want to do consulting ever again.
• Arrested Westeros - Arrested Development quotes atop Game of Thrones screencaps. Gold.
• Liquorious - drink recipes. Yes, I make my own bitters and thus like reading cocktail recipes :)
• Fashion It So - incredibly detailed fashion analysis of the costumes on Star Trek: The Next Generation. I do work at a fashion startup, you know!

What all of these have in common is that they don’t generate a lot of posts (Daring Fireball is probably the most prolific, and it’s usually just a few short link posts, with occasional long-form pieces). The posts on these sites are almost always very high quality - I want to read them and would regret missing them.

I can’t think of another technology besides RSS (and a great Reader client) that could more easily let me keep up with all of these websites.

What makes a good reader?

I’m currently using Reeder, which is available on iOS and Mac and it’s more or less perfect for my needs. It has a minimal, yet pleasing design, full keyboard navigation (j/k or GTFO), integration with various services (namely Instapaper) and, because it uses Google Reader as a backend, keeps me synced everywhere. It also works great offline, assuming you’ve downloaded your feeds when you were last online.

I’m hopeful that Reeder will come up with a new backend and just continue working. Otherwise, I’ll be looking for new options.

But RSS is (I hope) far from dead.

UserVoice’s approach is different: they made a DSL for describing service calls. The thing is, it’s sort of a type system - and a verbose one at that.

UserVoice’s approach is called “mutations” and it’s more than just method calls. You can specify quite a bit about our service calls, all to make the underlying logic very simple. For example, they have a “user signup” service and, in the most naive, but safe, way, it would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class UserSignupService

  def self.signup(name,email,birthdate,newsletter_subscribe=false)
    raise "name is required"    if name.nil?
    raise "email is required"   if email.nil?
    raise "email must be valid" unless email =~ EMAIL_REGEX

    user = User.create!(name: name, email: email, birthdate:birthdate)
    NewsletterSubscriptions.create(email: email, user_id: user.id) if newsletter_subscribe
    UserMailer.async(:deliver_welcome, user.id)
    user
  end
end

user = UserSignupService.signup(name,email,birthdate)

This is a very paranoid, but rock solid implementation. If you screw up calling it, you’ll know why. In Mutations, this code would look like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

class UserSignup < Mutations::Command

  # These inputs are required
  required do
    string :email, matches: EMAIL_REGEX
    string :name
  end

  # These inputs are optional
  optional do
    boolean :newsletter_subscribe
    date :birthdate
  end

  # The execute method is called only if the inputs validate. It does your business action.
  def execute
    user = User.create!(inputs)
    NewsletterSubscriptions.create(email: email, user_id: user.id) if newsletter_subscribe
    UserMailer.async(:deliver_welcome, user.id)
    user
  end
end
# ...
outcome = UserSignup.run(params)
if outcome.success?
  #
else
  #
end

This is fairly interesting, as the “business logic” (the code in execute) is clean - it’s just the bare logic. The sanity checking and other paranoia is handled by the framework. Likely that tests of this are simpler as well - you don’t need to test the validations. While this is great, I can’t help thinking that “every implementation of parameter validation in Ruby contains an ad-hoc, informally-specified, bug-ridden, slow implementation of a real type system”.

To demonstrate, here’s what this class would look like in Scala:

1
2
3
4
5
6
7
8
9
10
11
12
13

object UserSignup {
  def signup(name                : String,
             email               : Email,
             birthDate           : Option[Date],
             newsletterSubscribe : Boolean=false) : User = {
    var user = User.create_!(name,email,birthDate,newsletterSubscribe)
    if (newsletterSubscribe)
      NewsletterSubscriptions.create(email, user.id)
    UserMailer.async('deliver_welcome, user.id)
    user
  }
}
var user:User = UserSignup.signup(name,email,Some(birthDate))

That’s it. No special DSL, no custom framework, nothing. Just the programming language. Why?

First, we assume that null (Scala’s analog of nil) is always a bug. Good Scala programs are designed this way, and it’s not that bad to program without null, so a declaration like name:String in Scala means “name is a required parameter”.

Second, optional parameters use the Option type to indicate their optionality.

Next, for validating our email, we use the type system. Instead of using a String for storing email addresses (the hallmark of every stringly typed application), we require an instance of Email. We might imagine it looks like this:

1
2
3
4
5
6
7
8

class Email(var emailAddress: String) {
  if (!EMAIL_REGEX.matches(emailAddress)) {
    throw new InvalidInputError("Email address isn't valid")
  }
}

var goodemail = new Email("dave@foo.com") // all good
var badEmail  = new Email("dave.foo.com") // exception thrown

So, our UserSignup code can be absolutely sure that it gets a valid email. Validating that email happens elsewhere, as it should.

Finally, our callsite uses the same method that our class defines. Under mutations, you define a method called execute, but you call a method called run. Both just take a hash, making the callsite somewhat opaque as to what’s being passed in and requiring you to know how the framework works in order to piece together what’s being called. In Scala, you just call the method that you defined.

There’s no magic here, no framework, nothing other than idiomatic Scala code. I like the way it encourages us to create a rich set of types as opposed to strings and hashtables everywhere. Types allow us to encode our understanding of the system, domain, and logic - that’s what they are for. Statically checking that those types are used properly is a sanity check that we’ve correctly encoded our understanding.

Also note how not-that-verbose the Scala code is, compared to the Ruby code. The Java equivalent could not make that claim.

Anyway, I think Mutations looks like a cool library, and I plan on checking it out for writing Rails apps. I did think it was worth pointing out that the problem of separating argument validation from method logic is largely a solved problem - by statically typed languages.

I got an overview of their operations, and it’s amazing how well the business seems to work with almost no real automation (which is where the engineering team comes in). This sort of thing - writing software to make other people’s jobs vastly simpler - is what I love about programming. It reminds me of a particular user of the software I was writing for the US Marshals Service

I’d been there well over a year, and our requirements came from the government’s technical project manager. He was an old timer, knew the business, and gathered new requirements and features from the users (who were a wide variety of cops, administrators, and other IT people). But now, we were getting to meet some real users in a real district office. We talked to a lot of different people about how they used the software and, more importantly, what they did at their jobs.

Learning about Stitch Fix’s operations made me think of one person in particular from this trip. Her team handled transporting prisoners from jail to court - when a prisoner’s court date arrived, the Marshals had to make sure he was in a bus that morning headed to the courthouse from jail. Part of this woman’s job was to assemble that list on paper and hand it to the deputies in charge of prisoner transport.

Unfortunately, there was no specific feature in the software to generate and print this list. What she did instead was to call up the list on screen via a custom query. This was a VT100 app, so only about 20 prisoners were viewable on the screen at a time. She would then print the screen, and scroll to the next page, repeating this printing until she got the entire list. The result was a stack of papers with 80x24 screenshots printed on them.

And then she would cut out the list from each piece of paper before finally taping the lists together and copying it to hand off to the deputy. It took her well over an hour each day. And she wasn’t the only one doing this - it was the simplest way to assemble this list.

My colleagues and I were begging to fix this. It would’ve taken one of us maybe a day to fully implement, fully test, and deploy a report that would simply print out the list. But, it wasn’t a priority on the project plan, so it never got done. This was years ago, so I hope this poor woman has retired or that someone has fixed this.

At Stitch Fix, I’m looking forward to actually solving these sorts of problems. These really are the reason software is so great - minimal effort “typing shit into the computer” can save days for someone else. Sometimes I think my job is to eliminate the need for tape and scissors.

Now, I’m all for bad projects and bad code being called out. Our industry produces some shitty code, and a general lack of craftsmanship can kill business, or even people. So bad code needs to be pointed out.

The words I’m using here are a bit loaded, and actually distract from my real meaning. I don’t want to change the post, but thought it was worth explaining what I meant and why it’s important.

Uncle Bob actually weighed in on this debate in a recent post, and puts it much better:

(BTW, There is nothing wrong with politely pointing out what you believe to be deficiencies in someone else’s code. You don’t want to be rude or condescending when you do this; but you do want to do it. How else can we learn unless someone points out where we’ve gone wrong? So please don’t let this event stop you from valid review and critique.)

This is much more precisely what I mean, although this, too, carries the air of “I, the craftsman, am correct, and you, the mere code monkey, have much to learn”. What I’m really talking about is code review.

Code review (or code inspection) is one of the few software development techniques whose effectiveness at defect removal has been remotely proven scientifically. Anecdotally, it always improves the code under review, and frequently improves the way the code author and reviewers understand the problem. There is really no downside to code review.

Although a seasoned veteran developer is going to more quickly and easily identify issues with code under review than a developer with little or no experience, it doesn’t mean that the reviewer/reviewee relationship has to go this way - I’ve had developers more junior than me identify real issues with code I’ve written. No one writes perfectly clean or correct code the first time andk although tests help, tests only test that the code matches your understanding of the problem. It doesn’t take a 20-year senior developer to point out bad naming, poor API design, confusing structure, or a missed item from the requirements.

As to the phrases “called out” and “our industry produces some shitty code”, I mean this more as a call to arms to experienced developers. Make the time to review code - apply your experience to the work done by those who haven’t walked in your shoes. Everyone will be better for it. I wrote a post last year on how to do a code review that should provide you a good place to start.

As for unsolicited reviews of open-source software, I don’t know that trolling Github for “bad” code is the best idea, but if you put your code out there, expect (and embrace) commentary. Hopefully, it will be in the form of a pull request, but if not, you can still learn something and improve your code just via conversation.

Sure, I learned stuff about Rails, Ruby, service-oriented architectures, asynchronous processing, and credit card payments. But that’s not what I’m talking about. Those skills are great experience and will look just fine on my resume, but I learned two things that made me a better developer:

• Deliver results, not promises
• Assume everyone knows what they’re doing

Deliver Results, not promises

At a previous job, we had a well-tuned agile process. We worked in sprints, with a backlog, stories, and regular releases. After a while, however, it felt like the team was just producing story points. Products in development were allowed to be “in progress” for weeks or months. It got to the point where progress itself was a deliverable.

The problem is that promises, plans, and progress reports aren’t valuable in and of themselves. Promises don’t solve business problems. Customers don’t purchase progress reports, and developers can’t ship code based on un-executed plans. For whatever reason, LivingSocial gets this, and gets it deeply. When Mark Zuckerburg told Facebook’s shareholders that “code wins arguments”, I believe this is what he meant.

This cultural value leads to what I believe is the true essence of the “agile” movement. Consider for a moment if all you are as a developer is what you’ve shipped¹. This is going to fundamentally change how you work. You’re going to ship smaller features and you’re going to ship them more quickly. You’re going to deliver value to the business as quickly and frequently as possible.

Because of this, big projects - which is a project that might take more than a couple months - are unusual at LivingSocial and cause a fair amount of trepidation. In general, I believe this is a good thing. Big projects have a way of not shipping. Big projects have a way of getting bigger and more expensive.

I’m not saying that big projects are bad or that LivingSocial is incapable of taking on big projects, but we always ask ourselves if there’s a way to do a lot less a lot more quickly, and if we can start showing results sooner. This has not been a common attitude in anywhere else I’ve worked.

If your organization is truly “results-oriented”, then it means that promises, planning, and status reports are treated as fundamentally different things than shipped product. This isn’t to say that planning and progress are bad - LivingSocial certainly uses a wide variety of project management tools and techniques - but they are only valuable to the extent that they enable the delivery of results.

This attitude quickly affected everything I did, even down to the way I’d write email. I stopped immediately responding with “I’ll look into it”, or “I’m not sure”, or “That should be correct”. I started to respect the inboxes of others and responded only when I had a real result (or the name of the person who could get such a result if I could not). I stopped delivering promises and started delivering results.

Which brings us to the second thing I learned.

Assume everyone knows what they’re doing

Programmers have well-earned reputations as prima-donnas. While certainly not every programmer develops this arrogance and lack of respect for those who “can’t code”, it’s unfortunately common.

As a young developer, I was rude and disrespectful to anyone who didn’t code. I was allowed to get away with it because I did my job² well and my skills were in high demand. In my eyes, everyone was guilty until proven innocent. I even began to apply this to other developers after seeing what government contractors are allowed to get away with.

During my job prior to LivingSocial, I matured a lot in this area. I was fortunate to work with a great team of developers and with a largely effective, helpful, and talented team of sales and product people. As the company grew, however, my old attitude crept back - there were just too many people to know intimately, and I started to treat everyone new as incompetent until proven otherwise.

When I started at LivingSocial, this attitude persisted. The company is huge and, as one of only two developers working on a key piece of infrastructure, I had to interact with a wide variety of people. I knew enough to be nice and to be polite, but this was initially a mask of my lingering bad attitude.

After a while, I started to notice that the stereotypical programmer attitude was not nearly as strong at LivingSocial as anywhere else I had worked. The relationships between the developers and every other part of the company - customer service, IT, product, accounting - were far healthier than I’d ever experienced.

The result was a high functioning team that made decisions rationally, not politically. Developers were not rude nor disrespectful to their “non-techie” counterparts, and, surprise surprise, were treated with respect themselves. I don’t know how this evolved, but it seemed that everyone’s default assumption was that every member of the team was skilled, useful, and dependable - innocent until proven guilty.

As I realized this, and began to adjust my attitude, it became easier and easier to work with other people. Where in the past I would’ve dreaded having a meeting with the “idiot business guy”, I now went into these situations with an open mind, and a positive attitude - what business problem can I help solve? Turns out that people who don’t code are pretty smart and know stuff I don’t. The end result was that, in any discussion, the best idea would almost always win (and it wasn’t necessarily the developer’s :)

I have no idea how to cultivate or maintain this cultural value, but when a team of developers starts with the assumption that everyone’s working toward the same goal, and that everyone knows what they’re doing, the team functions well (and it’s a lot more pleasant to work on such a team).

Bonus third thing

In July, I wrote about the Hungry Academy graduates, who were all starting their new lives as LivingSocial developers:

The first half of this grand experiment is over and it was a rousing success. The second half - how well they succeed in the actual work environment - begins now. I’m optimistic.

It’s been about six months since I posted that and, in that time, I’ve had the pleasure of working with many of the graduates. I don’t know the ultimate cost of turning these 24 men and women into developers, but they are the most consistently skilled group of junior developers I’ve worked with. Hiring someone with little or no experience is always a crapshoot, and you hope that even 50% of your new hires will be this good. LivingSocial was able to produce twenty four of them in five months.

And they aren’t just code monkeys. Yes, they can make the computer do things, but their attitudes are amazing. They don’t seem saddled with any of the baggage that myself and my peers seemed to have at that point in our careers. It gives me hope that the “prima-donna developer” can someday be a thing of the past. Getting to experience their growth as developers is something I won’t soon forget, and likely something that very few professional programmers will get to experience.

Moving on

So that’s it. I’m moving on to work with some ex co-workers on a small team (more on that later), building a small, successful business into a larger, more successful one. My paycheck is going to depend on delivering results, and my ability to deliver those results is going to depend on good working relationships with all sorts of people working to make this business succeed. I honestly don’t know if this would be possible without my 14+ months at LivingSocial.