Before I became a software architect, I used to think that architecture was all about design, with a focus on imposing order across many modules. My former designer self instinctively likes code that looks nice.

But in one of our first meetings, my new boss quickly taught me it’s actually about efficiency. Design is just one way to get there. Software is more about maintenance than creation. Over many years, efficiency becomes key.

There are many ways to achieve greater developer productivity. In this post, I want to focus on conventions and saving time through less thinking.

Developer Intentions

I often annoy my colleagues with my neuroticism about how things are named. Why? Because I am neurotic and pedantic (sorry guys!). But more importantly, conventions let code speak for itself, revealing intentions to other developers, not just the author. Consider:

• order.create
• order.save!
• order.is_valid?
• order.destroy
• Order.all
• Order.find(15)
• Order.first

To every Ruby developer it’s clear which methods raise exceptions or are static - all without reading any documentation or code!

That is the beautiful thing about conventions. It’s not about strictly adhering to a dictator’s rules. It’s about collective efficiency for a team or community not an individual developer.

If a team can agree on a set of rules that everyone strictly adheres to, you will be a faster team because, you’ll instinctively know:

• what methods are available?
• what actions are destructive?
• which actions have side effects?
• etc.

All those questions have no business value to a product. But they cost developer time, not just to understand the code, which could be addressed with documentation. It can also cost developer time through bugs, introduced via unknown and undocumented side-effects. Every developer has done that, myself included.

Unintentional Side Effects

These are the most frustrating bugs because they can be difficult to trace. Which module changed the state and when? For example, how are you supposed to know that order.checkout() has side effects on customer? Ok, you could assume that. But how do I know what it changes and when without reading through lots of code or documentation?

That’s when I sorely miss Active Record Callbacks. In Rails it’s so easy to answer those questions by reading the top of a model, for example:

class Order < ActiveRecord::Base
  before_create :muddle_ip
  before_create :apply_coupon,       if: :has_coupon_code?
  before_create :charge_credit_card, unless: :is_free_order?
  after_create  :set_invoice_id
  …
end

Developer Happiness

So if architecture is about efficiency, why do I like code that looks nice? Because it’s efficient! In the Forward to Clean Code, author Robert Martin writes:

consistent indentation style was one of the most statistically significant indicators of low bug density.

— Robert Martin, author of Clean Code and the Agile Manifesto

Indentations style, seriously? Yes. And that’s the type of neurotic thing I often do to the surprise of colleagues when I first open a file. On some level, I am being superficial. On another level, some part of me learned that what I saw as “beautiful” code is actually “clean code”.

Through discipline and excellence tools like conventions can help us become more efficient teams via more productive and happier developers.