Code aesthetics

I’m not exactly the tidiest person when it comes to the physical world. I have two desks in my office at home; on top of one is a bunch of clutter and an LCD, keyboard, and mouse, so you might say it’s at least serving a purpose. The other desk serves no purpose other than forming the nucleus of another gigantic ball of clutter.

When it comes to code, though, I’m the most mind-numbingly anal perfectionist you’ve ever met. Ugly code—even if there’s nothing wrong with it aside from being messy—makes me depressed. It actually affects my mood. I can’t bear to look at it, much less work with it. The aesthetics of code have such a strong effect on me that I actively avoid languages that encourage or facilitate messy code and I try to avoid working with programmers who write messy code. I know this isn’t rational, especially if I want to continue to learn and grow as a programmer, but it seems to be hard-wired. I can’t help it.

One of my biggest pet peeves is when programmers fail to use vertical whitespace and descriptive comments to make their code more readable. Obviously you don’t want pages of blank space or comments on every line, but ideally whitespace and meaningful comments should be used to break up code inside a function into logical groups. This makes the code more readable in the same way that paragraph breaks make text more readable.

The following example is a more or less randomly-chosen snippet from a Ruby Flickr library I wrote a while back. Exhibits A and B are absolutely identical, except that B has vertical whitespace and comments, whereas A does not.

Exhibit A:

def sign_request(request, params)
  if @api_secret.nil?
    request.set_form_data(params)
    return request
  end
  params['auth_token'] = @auth.token unless @auth.token.nil?
  paramlist = ''
  params.keys.sort.each {|key| paramlist << key << URI.escape(params[key].to_s)}
  params['api_sig'] = Digest::MD5.hexdigest(@api_secret + paramlist)
  request.set_form_data(params)
  return request      
end

Exhibit B:

# Signs a Flickr API request with the API secret if set.
def sign_request(request, params)
  # If the secret isn't set, we can't sign anything.
  if @api_secret.nil?
    request.set_form_data(params)
    return request
  end

  # Add auth_token to the param list if we're already authenticated.
  params['auth_token'] = @auth.token unless @auth.token.nil?

  # Build a sorted, concatenated parameter list as described at
  # http://flickr.com/services/api/auth.spec.html
  paramlist = ''
  params.keys.sort.each {|key| paramlist << key << 
      URI.escape(params[key].to_s) }

  # Sign the request with a hash of the secret key and the concatenated
  # parameter list.
  params['api_sig'] = Digest::MD5.hexdigest(@api_secret + paramlist)
  request.set_form_data(params)

  return request
end

This function isn’t the least bit complicated, but Exhibit A sure makes it look like it is. Exhibit B, on the other hand, breaks it into meaningful chunks and uses comments to tell you what each bit is doing, so that a programmer unfamiliar with the codebase can see at a glance what’s happening without having to parse the actual code.

I probably spent an extra minute or two writing those comments and adding whitespace, but that up-front investment was well worth it when I found myself looking at that code again today for the first time in months and understood it instantly.

Do your future self and your fellow programmers a favor: comment your code and use whitespace to make it more readable. Only assholes and Perl programmers think cryptic code is impressive.