13 July 2009 · About 4 minutes read

Code: Being Conventional

Moving to Ruby on Rails has been great for helping to develop my coding skills, and I’m now adapting what I produce in other languages and projects to take advantage of the patterns used in Rails. One of the most useful has been convention over configuration:

[Convention over configuration] decreases the number of decisions that developers need to make, gaining simplicity, but not necessarily losing flexibility.

Convention over Configuration, Wikipedia

In this sense, being conventional is writing code that meets expectations. Asking what another developer would expect my code to do without their intervention? An example in Rails is the options hash used at the end of many method signatures (e.g. link_to, ActiveRecord::Base.find, etc.). It’s far easier to be able guess a method’s name or signature based on convention, rather than looking up API documentation.

Using convention throughout your project reduces the learning overhead for developers who are new to the team. Documentation becomes easier to write and maintain; it could simply be a reference to another well-maintained document. Even if your team hasn’t written documentation, following convention means that some form of help is likely to be only a web search away. This is much better than a bespoke set of ideas that are buried in the mind of the developer who left sometime last year.

Below are some of the conventions I’ve recently been working to adhere to:


Although I’m moving everything to git, I still use Subversion at work. The SVN book recommends that that your trunk folder should always be stable and releasable, whilst development should be carried out in branches, which are then reintegrated to the trunk as they are finished.

Functions and Methods

Many method signatures in Rails follow the format method_name(required_param, [options hash]) where options is a single hash of optional parameters. Every option is given a reasonable default, even if that default is nil). I find this convention great, as often code I’ve written has suffered from ‘parameter bloat’ as requirements change and expand. I’m now implementing the options hash convention not only into Ruby code, but also PHP projects using array_merge, e.g:

```phppublic function method_name(id, array $options = array())


$options = array_merge(array(

'option_1' => 'default',

'option_2' => 'default'

), $options);

# …


Deployment Scripts

In the past, I’ve written bash scripts to handle checkouts and uploads, but these are always fragile as they are heavily coupled with the underlying development and server environments. Since learning about and using Capistrano for Rails, I am now moving all my projects to use capistrano recipes. I can’t recommend this enough, and have used it for both Rails and PHP projects, with Subversion and git backends. Capistrano is well-document, adaptable, and under active development.

Server Configurations

It makes deployment easier to match your development environment exactly to your testing and live environments; a different point release of PHP or some abstract library can lead to hours of unnecessary debugging. To help keep everything in sync, use your distribution defaults where you can. For example, choose a Linux distribution and use the default packages that it provides (I use Debian 5 stable). It’s also much easier to rebuild or duplicate your server if you can just script an installation to get your server up and running. If you do need specific functionality or newer libraries, compile them into a package (e.g a .deb) and keep them somewhere safe for future use.

Using convention doesn’t mean building dull code. Rather, it helps to encourage debate, and drive innovation in developing better practice. As shown by ideas such as open-source, freely discussing, developing, and refining helps to define conventions and improve the experience for all developers.

Do you use conventions in your code and software projects? Please share and discuss in the comments.

Chris Blunt
Chris Blunt@cblunt
Chris is the founder of Plymouth Software. As well as code and business, he enjoys being a Dad, swimming, and the fine art of drinking tea.