So I decided to do something about this. Every single day, I spend at least 5 minutes learning something new that saves me time. I notice a repetitive motion, and I write a vim mapping, a shell alias, or a utility script, or just spend time looking at what other people are doing. It’s sometimes hard to step back and be self aware about the things that I repeat, so I try to watch how others work too. Then I go and write a shortcut. This small investment every single day, pays huge dividends because I get exponentially faster at the mechanical parts of my job every day, leaving more time for thought and productivity.

I like doing this, and I like sharing my learnings with the world. If you want a peek at how I do things, check out my dotfiles project, YADR. Fork it, copy it, steal the bits that you like, or contribute some of your own. Huge wins stand on the shoulders of lots of tiny ones.

As software developers, ops guys, designers, it is a known evil that we sometimes choose shortcuts, accruing tech debt with the knowledge that we’ll pay for it later with considerable interest. However, there are a few categories of design choices that we make every day that will make software easier or harder to maintain for the next guy who comes after us, which are specifically evil and malicious forms of tech debt.

Here are a few basic categories that most non-Maintenance Driven decisions fall into. Please don’t be that guy :)

• duplication – This is the cardinal sin against Maintainable Design. If you duplicate code, it will instantly grow into piles of subtly divergent crap. It would have taken you an additional hour to figure out how to do it in a non-duplicated way. It will take your maintainers half a lifetime to understand why and how the code has diverged. My own anecdotal experience says that duplication has about a 1000% tech debt interest rate. That is, 1 hour saved by committing duplicated code will cost you 10 hours down the line. And this interest is compounded over time as the code diverges further.
• clever code – Clever is the enemy of Maintainable. Every time you cut and paste a really cool hack that you found on a blog in 2006, a unicorn dies. Follow conventions, and use existing and accepted practices instead of reinventing the wheel.
• personal aesthetics – Having a strong sense of personal style is awesome. You like snakeskin jackets and neon green pants? Sweet. But leave it out of the code. If you have a personal style that goes against accepted conventions, and you choose to prioritize your style over that of the community, you are not Maintenance Driven. When in doubt, look at the source code for a large community supported project (i.e. Rails) for style ideas.
• poor naming – Single letter variable names are impossible to grep for effectively. Names based on your favorite ninja turtles, though they will win you points with me, are bad for business. Same goes for commit messages – don’t write something clever and witty at the expense of clearly explaining your changes.

If you like these, you might want to check out my Yet Another Dotfile Repo project, which includes these and more!

Since vim automatically loads everything in ~/.vim/plugin/, you can just add a directory like ~/.vim/plugin/settings and put each semantic piece in its own snippet. Put your keymaps in ~/.vim/plugin/settings/keymap.vim. Put your visual setup like font and colors into ~/.vim/plugin/settings/gui.vim, etc.

After I did this, I ended up with a vimrc that’s only about 90 lines long including very detailed comments about every section.

I think this is the cleanest vimrc you’ll see on the web. All my vim plugin settings are broken down into individual files, following a convention of one file per vim plugin that I use, plus some extra ones that are too small to be plugins.

Think your vimrc is better? Show me! I want to learn :)

My vimrc and the rest of my vim setup is available as part of my YADR (Yet Another Dotfiles Repo) project. Come check it out, I need alpha testers!

Blazing fast way of finding references to the current partial you’re viewing using this simple script. Requires git-grep.vim. Bonus: at the bottom of the script I also define “K” to git grep the current word. Very handy for fast function reference finding.

Like this post? Here are some more you might enjoy:

• Five ways to get insane productivity boosts
• Colorful ruby tests and debugging

Bet your TextMate can’t do this! Screenshot first, how-to follows :)

And now the how-to…

ConqueTerm for a color-enabled embedded vim terminal

ConqueTerm is pretty magical. It gives you an embedded shell where you can run bash, rib, rake, really..you name it. All with full ansi color support. This lets us run red green tests that actually look green and not as a bunch of ansi escape codes.

• Homepage
• Direct Download Link
• Install: follow directions on homepage or just :so conque_2.3.vmb from vim and restart

Setting up aliases for running bash, rails console, and irb

Put this snippet into your .vimrc. This will give you a few aliases to use in vim:

• \r for ruby on the current file as a ruby executable (great for unit tests)
• \R for Rake, great for running the entire test suite
• \S for RSpec on the current file
• \i for irb (actually pry)
• \c for the Rails console
• \b for bash
• \e to evaluate the current selection in the already open console

To get your tests to run red and green, gem install redgreen and require 'redgreen' in your test helper. By using the above \r alias with your ruby files, you will now see the output of your red green tests inside the colorized ConqueTerm. You can also run rspec colorized in ConqueTerm.

Variable inspection and debugging with Pry

gem install pry is one of the most brilliant and useful things I’ve seen. Simply by requiring this gem in your code and then adding a binding.pry in the spot where you want to break, you will be dumped into a very nice (and again colorized if you use the ConqueTerm) debugging context where you can inspect any variable by simply typing its name.

The other cool thing is that Pry lets you treat your code like a filesystem (try ls and cd [varname] to dive into complex objects). Try it out! You can also use pry as an irb substitute. Simply type pry at the bash command line, or use script/console --irb=pry with your Rails 2.x project. Here is an page on pry’s github site on how to set it up in other environments.

Pry does a whole ton more including the ability to create ‘macros’ in your irb, but that’s a whole different post.

Enjoy!

A developer who is afraid to mess things up asks himself: what is the absolute minimal change I can make to fix the symptoms without affecting underlying behavior. The answer involves creating some workaround, patch, or quick fix that hides the problem at hand without addressing the underlying cause. The upside is the developer feels safe – by making a minimal change he has taken on minimal risk, and he probably won’t get yelled at for breaking things.

But fear of change has a big price. Every piece of code that patches a symptom instead of fixing deep seated issues is moving the codebase towards less maintainability. Even if it lets us squeeze a release out today, it’s a hidden burden on future releases, and it’s a huge burden on every developer that comes to fix it later.

When you don’t continuously work to improve old code, you risk the failure not only of the product, but the entire team. Developers throw their hands up, leave the company, and new developers don’t want to touch legacy code. The Rewrite is declared, but without addressing any of the underlying Fear in developer DNA, we are bound to repeat the same mistakes.

The correct question to ask is: what is the root of the problem, what else in the system may be affected by it, and what do I need to change in order for this system to be more maintainable tomorrow than it is today. The answer to this question is usually not easy, takes longer to implement, and is harder to explain to your boss, who wants the product out next week. But it’s nevertheless the right question to ask.

To create maintainable systems that survive the test of time and, perhaps more importantly to the company’s survival, create code that is inviting to new developers as we grow the team, we have to develop from a position of confidence rather than fear. Here’s how we get there:

• Declare one day of the week testing/refactoring day where no new functionality is developed, and everyone is asked to pick a part of the system that is turning into unmaintainable legacy code and bring it back to life. This is a minimum, not a maximum. Refactoring should be constant and ongoing.
• Add tests to provide an insurance policy against breakage. If working on a part of system that is untested, write tests first before making your changes. Change is less risky with the safety net of tests underneath you.
• Encourage collective code ownership. It’s fine for one person to be the thought and code leader on a project but if no one else ever looks at that code, it is feared by the rest of the team, and the success of the project rests on a single developer. If he leaves the company, the project is finished.
• Use code reviews to minimize risk of large changes and encourage a team effort in cleaning up the system. Ask developers to spend half of their refactoring time reviewing and/or refactoring code from a part of the system that is not their own.
• Encourage code walkthroughs (distributed teams, use screencasts). Create a time and place for people to show off techniques they used, or just introduce others to parts of the system they may not be familiar with.

Code tends to outlive jobs. When we create code, we are not writing for ourselves, but for an audience of peers and progeny that will look upon it and have to maintain it. Do we want them to do so with awe and respect, or with fear and disgust? Writing maintainable code not only makes our life easier, but the lives of those around us, and garners admiration, praise, and rewards – if not always financial, at the very least karmic.

2. Establish a clean framework for future changes

If we start writing new code, and the pattern we establish is that we’ve copied and pasted a line across ten functions, what will happen when someone else comes along to add an eleventh function? Let’s face it, even the neatest programmers can get lazy. If something has been copy-pasted ten times, it will get copy-pasted for the 11th time, and a year later, when we find out we have to change the logic or content of that line, we are now changing 50 lines where we could have had one. Untangling code is always a lot harder than writing it, and we could have prevented the spread of the copy-paste disease by evaluating our code initially for repetitive statements. Always establish a framework for others to follow by writing clean code that reduces repetition, and encourages maintainability by isolating each piece of logic and content to one spot only.

3. Be brief, self-descriptive, and avoid inline comments

Five line functions with descriptive names are easy to understand. They require no comments. Thirty line functions take quite a bit of brainpower to digest, and usually have smelly comments scattered all throughout trying to explain bits of the function. Hundred line functions are an assault on all that is holy and stink to high heaven. If we see lots of comments interspersed in a method, it is a good sign that the code cannot be easily understood. Break it down into lots of little functions with descriptive names, and all of a sudden our code reads like a very clear and concise recipe, and we find that the comments become redundant. Most comments that live inside functions are parasitic organisms, treat them with suspicion.

4. Follow language standards and community conventions

If we break conventions, the next person to read our code will wonder why we did so. When our code raises questions about its style, the reader may start wondering if there was some specific reason that we coded it that way. Worse, they may perpetuate our unusual style through imitation and copy-paste tactics. This makes code harder to understand and wastes other people’s time. I’ve heard an argument from more than one person that they will code with the style they are comfortable with rather than follow language convention. This is especially true of people migrating from one language to another without investing their time in learning new habits and techniques. Remember that most of the time, we are writing code that someone else will be maintaining. Make their job easier by conforming to widely acknowledged standards, so they don’t have to spend any extra mental energy reading through it. It may take we a larger effort initially, but it will pay off with dividends when it comes to maintenance.

5. Really learn the language and the framework

Lots of bad code is written because of language or framework ignorance. If we don’t know the framework we use, we might reinvent the wheel or write obtuse code because we’re not taking advantage of the conventions and helpers already created for us. No need to be a walking encyclopedia, but remember to occasionally open up that encyclopedia and read through it so that you know at least what’s out there. I am sometimes surprised by new things I find in a framework I’ve used for quite a while, that makes my life a whole lot easier. Don’t neglect the docs, and don’t neglect to keep up with blogs that discuss new techniques.

I’m not really back, I’m just pretending. That’s all for now :)

I was recently designing an application that needed to execute some long running requests against an external host. If you’ve ever tried doing something like this in Rails, you’ll find your mongrels will block up waiting for the request to complete, bringing the experience for all other users to a halt.

I wanted to dispatch my long running request, return to the user, and then poll for results using AJAX. There are many ways to do background tasks in Rails, most of which require running an out of process background server with which you will communicate over some sort of queue or memcached. There’s BackgroundRb, Bj, workling, and so on, but this seemed overkill for my problem.

After reading a post on using Ruby Threads, I decided to be brave and try this approach. I implemented a simple action which would spawn a thread and proceed to return the result whether it was ready or not. This action is polled via AJAX and on the next poll the result will be correct. The pseudocode looks something like

def long_running_action
  #spawn a thread
  precache_the_results

  # This action throws DataNotAvailableException
  # if file is missing/unreadable
  results = read_cached_results

rescue DataNotAvailableException
  # This tells me that when I load the page
  # I should invoke an ajax a couple seconds
  # later to check for results again
  flash[:update_right_away] = true
ensure
  respond_to do |wants|
    # render an RJS update with the results
  end
end

def precache_the_results
  Thread.new {
    expensive_action_outputs_to("file.txt")
  }
end

Because I didn’t join the Thread to the request thread, it lives on after the request completes, which is just what I needed. Since the code inside my Thread is a call to an external provider and doesn’t write to the database, I am not concerned with ActiveRecord threading issues.

The only problem with this approach is that in development mode, Rails likes to reload your classes on every request. But if your thread runs past the request lifetime, the class that’s running it may be unloaded while it’s running, wreaking all sorts of havoc. But Ruby allows us the power to be truly evil:. What if I just prevent Threads from doing what they want to in development mode? Turns out I can!

if ENV['RAILS_ENV'] == 'development'
  class Thread
    def initialize(&block)
      block.call
    end
  end
end

This code is defined in the class where I’m doing the magic. Do NOT just slap this into your environment.rb as you’ll horribly break the Rails startup logic. There’s probably a slightly smarter and safer way to do this by using a Factory pattern to create the threads and explicitly specifying the implementation you want. But this is my party and I’ll monkeypatch if I want to.

So..comments, suggestions, complaints? Is this going to die horribly in production? I guess we’ll have to see!