This site provides the following access keys:

Brandan Lennox's

Code Hygiene

The second law of software thermodynamics:

Your code tends toward higher entropy. Brandan Lennox, 2012

The Problem

The more code we write, the harder it is to tell useful code from useless code, and the longer it takes to turn the latter into the former.

The Amalgam

These examples all come from our Rails project at work.

  1. For three and a half years, the code, which isn’t public or user-accessible, still contained the default README and an empty doc subdirectory.
  2. We use Workling for background jobs. Mainline development on Workling stopped in 2009, and it’s no longer compatible with Rails 3.1. Same with Machinist.1 Same with Spork.2 Our adoption of a project is a death sentence.
  3. Until recently, we had four separate subdirectories housing executable scripts: bin, script, runners, and utils. Only script is Rails-sanctioned (and necessary).
  4. We have to execute asset precompilation in a custom Rails environment — i.e., we can’t use the production environment like you would expect. I don’t know why. In addition to that, one co-worker recently created his own environment for development. I guess he wasn’t happy with development or production, so he combined the two. So now we have 66% more execution environments than a normal Rails project.3
  5. Speaking of environments, we have a custom initializer for our test environment that adds 10,000 to the current autoincrement value for the id column of certain tables. That’s how we fixed a conflict between Postgres, fixtures, and Machinist. We’ve switched from Machinist to FactoryGirl, but we left that initializer in place because insert reason here.

The Stink

It’s not just a matter of refactoring. I find a lot of code that isn’t even executed anymore. It’s just taking up disk space and attention, but you can’t know that until you spend the time to figure out what it does.

And it’s not just a matter of compulsion. The problems I listed above really do hurt us:

  1. Okay, maybe not this first one, but…
  2. We missed a release date because of a bug in Workling that we didn’t find until the very end of the test cycle. By then, we didn’t have time to replace Workling with a current tool, so we hacked around the bug and released. Is that going to bite us once it’s out in the field?
  3. If I want to create a new executable script, which directory am I supposed to put it in? What’s the difference between a runner, a script, and a util? Who’s executing these scripts, and do they have a good reason for this arbitrary directory layout? Why am I having to make this decision?
  4. Why did someone have to create a precompile environment? How is it different from production? How do we know if a future version of Rails fixes whatever problem we had with asset precompilation?
  5. We spent so many hours fixing problems with Machinist that were never going to be fixed by its developer. But FactoryGirl seems to work fine. Do we still need to futz with these autoincrement values? It slows down our tests and represents a significant break from normal development. Is something else depending on that behavior, or can we get rid of it?

The Cleansing

I need to learn to balance my compulsion for pristine code with my requirement to produce. It wasn’t a big deal when I worked by myself because the projects were small, short-lived, and completely owned by me. Now, it’s not just a poor use of time, but it creates tension between you and me if I’m always rewriting your code without good reason.

In related news, I’m going to start writing a lot more code for myself :-)

Footnotes

  1. Stuck in 2.0.0.beta2 since July 2010.
  2. Spork 0.9.0 will be compatible with Rails 3.1, but 0.9.0.rc9 was released in June 2011 and somehow still hasn’t made it to final. The last commit on Github was November 8, 2011. Curiously, the only reason I know about Spork was a flurry of activity early last fall. What happened to it?
  3. Not to mention the selenium environment I recently removed. We haven’t run Selenium directly against our Rails app in at least the two years that I’ve been working there.