Here are my notes on Xavier Shay’s awesome video on sustainable productivity in Rails. I agree wholeheartedly with all of his points, and although they’re not particularly new, it’s nice to hear from someone with real world perspective on maintaining a large Rails project.

1. Rails does not make data integrity a priority, so be conscious of it and take the effort. Ideally the framework will evolve in this direction eventually.
   • validates_uniqueness_of doesn’t validate uniqueness with concurrent access – you need db constraints (unique indexes, foreign keys, etc). At the same time, Rails doesn’t provide a good built in way to error handle constraint violations.
   • Rails encourages poor practice with database because things like t.references in migrations doesn’t add foreign keys.
   • (personal note) I have seen many Rails projects completely ignore database keys. I like the old adage that your database will outlive your application. Put constraints where they belong.
2. Consistency is incredibly important, and is more so when you have a large team. If you create two ways of doing one thing, the next developer has to scratch his head. Don’t duplicate code or concepts, design for reuse.
3. Don’t pepper third party dependencies in your code. Design layers of abstraction so that all third party access is in one spot, easy to change. Use reification – start naming concepts rather than implying them with conditional logic (e.g. the Null Object pattern).
4. “Fail your build for basic style, complexity, and readability violations.” Don’t let people check in stuff with bad whitespace, complex methods, etc. Make it part of the continuous integration cycle. Bad code spawns more bad code. Easier to prevent in the first place than untangle later. (see: cane, also metric_fu)
5. Self-documenting code is awesome, but documentation should be used on a class level to describe how the class figures into the bigger picture. I’m a huge fan of this idea, and don’t do it enough myself.
6. Rails unit/functional/integration test definitions are different from everywhere else in the world. They tell you how to organize code but are not useful, leading us to have “fast spec” vs “slow spec”. This is bad. A unit test should not touch the database, filesystem, etc. Unit tests should be fast and without dependencies, integration tests specify boundaries, acceptance tests make sure the system works.
   • (Personal note) At Crowdcast we have been working purely with fast-spec lately, even stubbing out dependencies in our controller tests so we can blazing fast TDD our code through the entire stack, relying on a single high level acceptance test that makes sure everything connects correctly, and stubbing everything at lower levels.

Videos are awesome but not everyone has the time. I made these notes for myself but if people find them useful, I’ll try to continue blogging short summaries of talks that I watch. I hope others do the same, so we can save each other time :)

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.

1. With your cursor over the thing that’s highlighted in a bad color, hit the ,hi. Say I don’t like the way this describe keyword is done in pink:

2. Note the info displayed in the status line, it will look something like:
hi<rspecGroupMethods> trans<rspecGroupMethods> lo<Todo> FG:#d33682

These are the color highlight groups, in brackets. The leftmost one is the one with highest precedence, and the one we want to override.

3. Look at the list of available colors using :hi. Note the names of the groups on the left, and their displayed colors. Find one you like. The list will look something like this:

4. Create a link between the group you want to modify and the one you like. Let’s say the one I like is Identifier, and the group I’m modifying is MatchParen. I would link them like this:

hi! link rspecGroupMethods Type

Reload your vimrc, or the file in which you placed the statement. The easiest way to evaluate the current file is :so %. And voila:

You can place this in your ~/.vimrc, or in a subfile under ~/.vimrc/plugins. If you liked this example, be sure to check out my highly customized dotfile project called YADR, which offers the ,hi functionality, well organized vim snippets and plugins, and other handy shortcuts to save you tons of time.

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!

For more awesomeness, check out my dotfiles repo called YADR (Yet Another Dotfiles Repo), featuring 100% clean vimrc with all custom keymapping done in well factored scripts inside vim/plugin/settings, and a list of plugins perfectly tailored for Rails development, currently in alpha preview.

Using vim is like talking to your editor in ‘verb modifier object’ sentences, turned into acronyms

• learn some verbs: v (visual), c (change), d (delete), y (yank/copy). these are the most important. there are others
• learn some modifiers: i (inside), a (around), t (till..finds a character), f (find..like till except including the char), / (search..find a string/regex)
• learn some text objects: w (word), s (sentence) p (paragraph) b (block/parentheses), t (tag, works for html/xml) there are others

To move efficiently in vim, don’t try to do anything by pressing keys many times, instead speak to the editor in sentences

• delete the current word: diw (delete inside word)
• change current sentence: cis (change inside sentence)
• change a string inside quotes: ci” (change inside quote)
• change until next occurrence of ‘foo’: c/foo (change search foo)
• change everything from here to the letter X: ctX
• visually select this paragraph: vap (visual around paragraph)

If you understand the verbs and objects you’re dealing with, you will soon realize that adding a new plugin and learning a new verb or noun exponentially increases your productivity, as you can now apply it in all the sentences you already know. It’s just like learning a language.

Let’s add some new text object plugins!

• install surround.vim: vim-surround- you get a new noun, the ‘surround’ (s or S)
  • visually select a word and surround it with quotes: viwS”
  • change surround from single quote to double quote: cs’”
• install vim-textobj-rubyblock – you get a new noun, the ‘ruby block’ (r)
  • delete current ruby block: dir (delete inside ruby block)
  • visually select a ruby function: var (visual around ruby block)
  • visually select the innards of a function: vir (visual inside ruby block)
• install tComment – new verb: “gc” (go comment)
• comment the current ruby method: gcar (go comment around ruby)

Now go out and learn a new verb or noun every day!

Resources and Further Reading

• Vim Text Objects, Definitive Guide, a great blog post!
• Want an exceptionally curated collection of the best plugins vim has to offer? Check out an early beta preview of my fully modularized vim/dotfile setup called YADR (Yet Another Dotfile Repo) which includes text object plugins for ruby blocks(r), indents(i), dates(da/df), function arguments(a), and ruby symbols(:)

These commands are not only extremely useful but also mnemonic and easy to learn for a huge payoff in keystroke savings. These are the common compound commands I use every day, and I think it’s easier to dive in this way than to try to learn vim key by key.