In an earlier post, I wrote about how the code I’m most proud of is terrible code. This is because although the code is terrible when I come back to it to change something after 6 or 12 months I can quickly find where the change needs to be made.

When describing this to someone they asked me why it is easy for me to navigate the codebase. Obviously, this code came out of my head so I have an unfair advantage here, I can’t pretend this is not a factor.

That, by itself, is not an answer though. I have other code I could point to that “came out of my head”, yet it is not easy to understand or change months later.

What I think makes the difference with this codebase is that it follows a set of naming conventions, even if they are unconventional ones.

The codebase is a typical Model-View-Controller (MVC) architecture. The routes are not RESTful, but the methods in the controllers are named after what they do. Methods that expect a post HTTP method have a post prefix. Methods that are hit from an AJAX request have an ajax prefix. Logic is in the controllers (fat controllers, if you will) but at least this makes the logic well contained and easy to find.

Examining this made me think about the power of conventions, and the benefits that come from ecosystems that place strong importance on conventions.

I’ve noticed that developing naming conventions like this is a strong tendency in my day-to-day coding. Even in the GitArborist codebase (a GitHub app for managing pull request dependencies), I have conventions. Some interactors have a Handle prefix, others have a Process prefix, etc. In all cases, the prefix gives me a clear indication of what I expect that class to do and where I expect it to be called in the chain of business logic.

Trouble managing your Github Pull Requests?

GitArborist was created to simplify Pull Request management on Github
Mark PR dependencies, automatic merging, scheduled merges, and more →

Code I encounter tends to be in the following groups:

  1. Simple code, usually doing simple things
  2. Code that is complicated because the problem it is solving is complicated
  3. Code that is complicated because the programmer has made it that way.

You see this all the time when non-developers write code. Find someone with no coding experience who’s made a complicated spreadsheet and you’ll probably see how it’s become complicated because they aren’t trained in the coding disciplines to keep it maintainable.

Naming conventions are not a panacea, but I think they can help us avoid situation 3, even if the conventions we use are unconventional.