mcramm.com

Watch Yourself

2012-01-27T00:00:00-08:00

Every week since the new year started I’ve been getting asked what my New Years resolutions were for 2012. My answer the first few times was the truth: “I haven’t decided yet.” Almost magically, the focus will shift to the other person and they’ll explain to me that this year they plan on being more active, do more travelling, etc. At this point my attention will wane my eyes will gloss over and the words “Oh, nice!” fall out.

I’ve noticed that most people don’t hit these kinds of goals and I can’t tell if its because they’re to vague, unrealistic, that the person is lazy, or some combination of the three. With me I know that I’ll only hit my goals if they’re A) specific and B) obtainable. “I want to be more active” is a nice goal, and one that every sunlight bereft developer should strive for, but isn’t specific enough. “I want to learn how to perform a frontside-180” is pretty specific and completely obtainable for even for someone who has just started snowboarding.

When I sat down to pick a resolution for this year, I wanted to pick something about myself professionally that could use some improvement. I made a list. A long, very scary list that I’ve since hidden under my bed and don’t plan on looking at again until sometime mid-August. The list was good though, and it has definitely given me some stuff to think about. More importantly I was able to pull out a couple of resolutions from it that I are realistic enough, but will still require some diligence on my part in order to obtain.

Stop and Think

If I had to classify the first part of my career, I think I would label myself an “Idealistic Hacker.” When given a new problem, I would launch into an answer without thinking through the ramifications that came with it. I would typically look back at my newly minted solution and realise that it didn’t quite fit with the issue I was trying to solve. I would then spend more time hacking my hack until the requirements were met.

Obviously this was a problem. It worked for a while until I realized that I was wasting a ton of time not only with getting the feature shipped, but trying to re-understand my solution on a return trip to the module 6 months later.

I’m the kind of guy who appreciates well designed code and loathes the ugly. I take pride in designing my code well because I know that it saves time for the next person who has to read it. I’ve found through practice and experience that I can achieve my highest level of satisfaction when I’ve taken the time to truly think about a problem before I sit down to solve it.

This is in essence what Rich Hicky talks about in a presentation he gave called Hammock Driven Development

Undoubtedly there are times in our jobs where we aren’t afforded the luxury of taking even a day to think through a problem, but we should be able to at least spare a few minutes to make sure we understand the problem. I’ve come up with two really obvious tactics to force myself to come up with good solutions. The first is to throw an idea at a colleague and see what they think. Small, two minute discussions about a problem has saved me boatloads of time when designing a solution. The second is to make sure I write my tests first.

Practice TDD EVERYWHERE

TDD is something I’ve been practicing on my own for a while now, but I haven’t yet made the leap to using it full time at work. I don’t really have an excuse for this. Most of my colleagues believe in the practice, and everyone is in favor of writing tests. I just tend to get to so bogged down with problems from all different angles that I spend more time writing my tests after I’ve finished rather than before.

I decided this needed to stop when I began working on a module that had no tests associated with it. My problem was trivial: a date value wasn’t appearing on a client facing widget. The solution seemed simple enough. There was a default_display_value attribute on the widget that wasn’t being set during its creation so all I needed to do was add the correct date to the parameters being passed in. Alas, this appeared to do nothing and I spent the next hour following a maze of logic that only served to confirm that the code I was looking at had been hacked together.

I’ve vowed since then to always write tests for any code I touch first. I’ll do this not only because I know it will result in better code, but that the next developer will be able to expand upon it without worrying about breaking whats there.

By now you’re probably wondering why I titled this post “Watch Yourself” and not “Stop What You’re Doing and Write Tests!” To be honest, I originally set out to write something along those lines, but it felt overly preachy and has been done to death. I changed it to be more about myself and what I’ve experienced. I know what works for me because I’ve taken the time to look back at what I’ve done, determine where I’ve succeed, where I’ve failed and try to improve myself professionally.

You should too.

Tdd In Node

2011-12-18T00:00:00-08:00

TDD is discipline that I’ve been trying to master for a while now, and I’ve been absorbing every blog post, talk, or book I can get my hands on. One thing thats key for me is to have some way to run my tests very quickly. Even better, the tests should run automatically whenever code in application files or tests changes.

In Ruby, I have Guard. It works beautifully and does exactly what I need it to do. I spent the last week struggling to find something similar in NodeJs but didn’t come up with anything I liked. I found it frustrating, because watching for events on files or directories is something that Node should be good at. In the end I settled on writing a simple Cakefile:

    CoffeeScript = require 'coffee-script'

    {print} = require 'util'
    exec = require('child_process').exec
    fs = require 'fs'

    # ANSI Terminal Colors
    green = '\033[0;32m'
    reset = '\033[0m'
    red = '\033[0;31m'

    log = (message, color, explanation) ->
        console.log color + message + reset + ' ' + (explanation or '')

    compile = (callback) ->
        exec "coffee -o js -c lib", (error, stdout, stderr) ->
            if error is null
                log 'compiled!', green
                callback?()
            else
                log error, red

    test = ->
        command = 'jasmine-node --coffee spec'

        exec command, (error, stdout, stderr) ->
            if error is null
                log stdout, green
            else
                log stdout, red

    task 'build', 'Compile the coffeescript into javascript', ->
        compile()

    task 'test', 'Run the tests', ->
        test()

    task 'watch', 'Watch for file changes and compile into javascript', ->
        fs.watch 'spec', (event, filename) -> test()
        fs.watch 'lib', (event, filename) -> compile test

        compile test

This file is pretty simple and contains three tasks: build, test and watch. Node has an easy way to watch for file system events on directories through fs.watch <directory>.

I tried a couple of testing libraries, but settled on jasmine-node since I’ve used it before.

Now I can just run cake watch and start writing code. Occasionally I’ll stop and take a look at the other monitor to make sure everything is green. I used this process and ran through the classic Bowling Game Kata. I also posted the source on GitHub.

Vim Reboot 7

2011-12-06T00:00:00-08:00

Some other useful plugins

There are some other plugins remaining that I find quite useful, but don’t need to do much configuration for:

SnipMate - For quickly creating your own custom snippets.
Surround - For working with surrounding brackets. Need to change your "’s to '’s ? or () to []? Use Surround.vim.
Unimpared - Mappings for common operations.
NERD Tree - Sidebar that contains the structure of the current project. Useful for common file operations.
Endwise - Adds the ‘end’ keyword to certain structures automatically in Ruby.

Each of these plugins can be installed by simply downloading the zip and unpacking it in your ~/.vim directory.

Vim Reboot 6

2011-11-27T00:00:00-08:00

Command-T

I used Textmate when I first started learning Ruby/Rails and after I switched to Vim, I missed the ability to use the <Cmd>-t hotkey to quickly open up new files. What was so great about it was that you could hit the hotkey and start typing the name of your file to filter the resulting list. Once you had filtered the list enough to have your file appear at the top, you just hit <Enter> and the file would open as the active pane in Textmate.

After a bit of research, I came across Command-T. This plugin works in the exact same and can even be improved with some minor configuration.

Installing this plugin is slightly more involved than others. First, download the .vba, open it in vim and source it with :so %.

You then need to install the C extension:

cd ~/.vim/ruby/command-t
ruby extconf.rb
make

And the plugin will be installed! I would recommend doing the following configuration as well:

From my ~/.vimrc:

" Command-T configuration
" Set the max height to 20 lines
:let g:CommandTMaxHeight=20
" Show dotfiles like .gitignore, .rvmrc
:let g:CommandTAlwaysShowDotFiles=1
" The maximum number of files to search through
:let g:CommandTMaxFiles=20000
" Map ctrl-t to command-T since the meta key isn't available when using
" vim on the server
:map <C-T> :CommandT<CR>

And from my ~/.gvimrc:

" Set the mac meta key
macmenu &File.New\ Tab key=<D-T>
map <D-t> :CommandT<CR>
imap <D-t> <Esc>:CommandT<CR>

When you’re in a project, you can now hit <Cmd>-t and start typing the name of the file you wish to edit. You can scroll up and down the list by using <Ctrl>-j and <Ctrl>-k respectively. To open a file, just hit <Enter>. You can also open a file in a new vertical split by doing <Ctrl>-v, or in a new tab by doing <Ctrl>-t.

Setting the default leader key

It might be a good idea at this point to update the default leader key used to prepend any custom mappings you create. I always set mine to ,.

In ~/.vimrc:

" Set the leader
let mapleader = ","

Now you can do something like this:

" toggle line numbering on and off
map <Leader>n :set number!<CR>

When you hit ,n in vim, line numbers will be toggle on and off.

Command-T’s buffer list

Now that we have the default leader setup, we can take advantage of Command-T’s built-in buffer manager. If you don’t know what buffers are in vim then you should take a look at this page.

After you’ve opened/closed a few files, you hit ,b to see a list of any buffers open in the current session. In some cases, this can actually be quicker than using the standard Command-T interface.

There is an alternative to Command-T’s buffer window called LustyJuggler. I would recommend giving it a try if you’re not fond of how Command-T manages buffers.

Vim Reboot 5

2011-11-14T00:00:00-08:00

Plugins in VIM

Vim plugins can be enabled in a variety of ways. Sometimes all you need to do is copy the plugin.vim to ~/.vim/plugin. Other times the plugin comes packaged as a .vba file that you need to open in vim and source by executing :so %. In any case, you should always read the plugin’s README first.

Some people have gone out of there way to write vim plugins that make installing other plugins even easier. I have come across two such plugins in my research.

Pathogen was created by Tim Pope and has been around for a while. A couple colleagues of mine use it and seem to really like it.

Vundle was inspired by Bundler’s method of keeping track of rubygems for projects.

For the sake of these posts, I’m going to stick with the “vanilla” method of installing plugins. If you’re curious though, I would recommend trying out both of those plugin management solutions as they can make organizing your plugins much easier.

Tab Completion

I got to admit, all of the setup done in the previous posts was incredibly frustrating without tab completion. SuperTab is the best solution I’ve found. The plugin comes as a .vba file, which means installing it requires you to open the file up and type :so %.

Now when you are in your editor and hit tab, a handy dandy list of all possible matches will appear:

Nerd Commenter

Commenting lines in and out can get pretty arduous if you do it a lot. With Nerd Commenter, you can comment a line in or out by doing <Leader>ci. Make sure that you have filetype plugin indent on in your ~/.vimrc, as the plugin will use the appropriate comments for the language you’re in. There are a couple of other commenting formats available with the plugin, so you should look through the vimscripts page and try a few commands out.

To install, simply download the .zip file to ~/.vim/, and unpack it.

Ruby's Load Path

2011-10-29T00:00:00-07:00

One thing that always tripped me up when I first started writing my own gems was how to properly require other files when the files were relative to the current file’s path. Let’s say you have your classes laid out like this:

    app.rb
    lib/
        myclass.rb
        anotherclass.rb

How would you require those two files in lib? I quickly became used to doing something like this:

    require File.join( File.dirname(__FILE__), 'lib', 'myclass' )
    require File.join( File.dirname(__FILE__), 'lib', 'anotherclass' )

Which works, but has a lot of duplication. All I really care about is the name of the file I’m requiring, and that’s all the way at the end of the line.

In quicker, smaller projects, it was okay since I only ever needed to require one file at a time. On larger projects though, I began to do the following:

    path_to_lib =  File.join( File.dirname(__FILE__), 'lib' )
    require File.join( path_to_lib, 'myclass' )

This was better but it still felt like I was doing something unnecessary. Finally one day I was frustrated enough to look into what require actually did. How does Ruby know where to look when requiring a gem? If I want to use the Typhoeus library, I can just say require 'typhoeus'; I don’t need to specify the full path to its location.

Sounds like its time to check out Ruby’s Kernel module.

Ruby tries to load the library named string, returning true if successful. If the filename does not resolve to an absolute path, it will be searched for in the directories listed in $:.

Makes sense. All I should need to do is add the subdirectory I want to require to load to the path that Ruby scans through. Kernel’s rdoc says that the path(s) are stored in $:. Let’s see whats in there:

    p $:  # => ["/Library/Ruby/Site/1.8", ... ]

Looks like its just an array of paths. I should be able to simply add a path to the end of the array and Ruby should scan that directory when I call require:

    $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')

Again, this works, but $: dosen’t feel intuitive. Some quick googling shows that $LOAD_PATH is an alias for $::

    $LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')

    require 'myclass'
    require 'anotherclass'

Now you can see immediately which file is being required. Plus, if you’re writing a gem, you only need to do this once in the base class and the same load path will be used in any file beneath it.

Vim Reboot 4

2011-10-23T00:00:00-07:00

An Addendum

In a previous post I described how to get syntax highlighting working, but I forgot to add a setting to enable plugins and indentation based on filetype:

    filetype plugin indent on

Searching

Every vim user should know how to search for text within a file. In normal mode, hit / and type in a search string. Press Enter and your cursor will jump to the first occurance of that string. The following options make searching a little bit nicer:

    set hlsearch
    set incsearch
    set ignorecase
    set smartcase

hlsearch highlights every occurance of your search in the file after you press the Enter key.

incsearch moves the cursor and begins highlighting the search term as you type it.

ignorecase will make your searching case insensitve. Searching for “foobar” will match “foobar”, “FOOBAR”, and everything inbetween.

smartcase is used in conjunction with ignorecase. If your search term contains an uppercase letter, then the search will be case sensitive. Searching for “foobar” will work as before, but “fooBar”, will only match other occurances of “fooBar”.

Status Line

At the bottom of the vim window there is a status line that (by default) simply displays the name of currently open file. There are ways, of course, to customize this, and I’ll be doing a lot more with it in a later post. For now, all I want to do is insert the cursor’s current line/column number, and make sure that it is always visible.

    set ruler
    set laststatus=2

ruler displays the cursor’s current line and column number.

laststatus tells vim when to show it’s status line. It can have 3 possible values:

0 Tells it to never appear.
1 Tells it to only appear when there are more than 2 windows open.
2 Forces it to always be visible.

As I said, there are even more ways to customize this line, but for the customization I want to do, I’ll need to install a plugin.

This is the end of the most basic setup options. Next time I’ll start enabling the plugins that I use most frequently.

Vim Reboot 3

2011-10-16T00:00:00-07:00

Line Numbers

By default vim doesn’t show line numbers. I prefer having this as it can make finding the source of exceptions slightly easier, and you waste less time by telling the person you’re pairing with to go to line 12 instead of pointing at their monitor like an ape.

    set number

Whitespace

This section is pretty self-explanatory; it tells vim how to deal with whitespace.

    set nowrap

    set tabstop=2
    set shiftwidth=2
    set softtabstop=2
    set expandtab
    set autoindent
    set smartindent

nowrap tells vim not to wrap long lines of code.

tabstop tells vim how many columns a tab counts for. Most of the work I do is in ruby, and the standard there is 2 spaces.

shiftwidth tells vim how many columns text is re-indented with when doing « and ».

softabstop controls how many columns vim uses when you hit the tab key.

expandtab tells vim to use the appropriate number of spaces to insert when hitting tab.

Find the last few settings a little confusing? Check out this site for little bit better explanation. At work, we use PHP, and our standard is 4 spaces of indentation instead of 2. You can override these settings on a per file type basis by creating a filetype.vim in ~/.vim/after/ftplugin. For example, I have a php.vim file with the following:

    setlocal tabstop=4
    setlocal shiftwidth=4

autoindent simply copies the indentation of the previous line when starting a new one.

smartindent automatically inserts one extra level of indentation in certain cases.

There is one last thing I like to do that picked up from the Janus vim configuration:


    set list listchars=tab:\ \ ,trail:·

This tells vim to put a trailing character, · in place of any trailing whitespace. Again, this is more of a personal preference. I tend to be pretty obsseive about leaving my code and commits looking pretty.

Vim Reboot 2

2011-10-09T00:00:00-07:00

In my last post I installed MacVim and setup some very basic options specifically for it. For the next few posts, I’ll be focusing on features that can be applied to the more common, server-side version.

Syntax Highlighting

The first thing I wanted to have was some syntax highlighting.

    set t_Co=256
    colorscheme mike_wombat

    syntax enable

set t_Co=256 sets vim up to run in 256 color mode (I use iTerm 2).

colorscheme mike_wombat sets the colors scheme to a slightly customized version of the wombat color scheme. Like the ir_black theme from my previous post, this can be found here. Just move it into ~/.vim/colors to use it.

syntax enable enables syntax highlighting.

Backup Directory

Vim keeps a backup of any files you open in the form of filename.swp. If your vim session crashes, or the connection to your server times out, then you can use this file to recover any edits you’ve made.

The problem is that these files can sometimes get in the way. The most common complaint I hear is with these files getting included as part of a commit to a repository.

Some people choose to turn this feature off completely and not have these backups created at all. I think that these backups can be valuable and prefer to simply have them written to a different directory.

    set backupdir=~/.vim/backup
    set directory=~/.vim/backup

Any backup files will now be created in ~/.vim/backup. You may need to make the directory manually before the feature will work (though you should get prompted with an error when launching vim).

Vim Reboot 1

2011-10-02T00:00:00-07:00

Over the past few years my Vim configuration has gotten out of hand. I’ve tried to maintain it as best I can, but its time for a reboot. I was inspired by Avdi Grimm’s recent Emacs Reboot series and decided to do something similar for Vim.

I work on a Mac, which means I prefer to use MacVim where possible. The latest snapshot for Snow Leopard can be found at http://code.google.com/p/macvim/ and installing is as easy as you would expect. Simply download the snapshot, drag MacVim.app to Applications and move the mvim script to folder in your path:

sudo mv mvim /usr/bin

Using mvim from the command line at this point should launch MacVim as you would expect.

At this point, you have two options. You can continue with this series of posts on customizing your environment by hand, or you can check out Janus and get a very good default configuration. I used this initially and copied a bit of my configuration directly from it.

The first thing I wanted to do was fix the (ugly) default color scheme and setup MacVim to work in full screen mode.

Create a .gvimrc file:

touch ~/.gvimrc

And add the following to it:

if has("gui_macvim")
    " Make fullscreen mode take up the full screen
    set fuoptions=maxhorz,maxvert

    "set the font
    set guifont=Menlo:h10

    " Command-Return toggles full screen mode
    macmenu Window.Toggle\ Full\ Screen\ Mode key=<D-CR>
endif

" Start with the toolbar hidden
set guioptions-=T

" Set the color scheme
set background=dark
color ir_black

Substitute the “Menlo” font and “ir_black” color scheme with the font/scheme of your preference.

Menlo should be available on your Mac if you have Snow Leopard. If you don’t have it, then you should try out Bitstream. Installation details can be found elsewhere on their website.

ir_black can be found in a bunch of places, the best of which is here. You can use this scheme by doing:

  mkdir -p ~/.vim/colors
  mv ir_black.vim ~/.vim/colors/

Running mvim from the command line should present the following:

Next I’ll start setting up some standard vim options and a couple of custom mappings I use quite frequently.

Parameter Nam

2011-09-30T00:00:00-07:00

I recently finished a project to improve the design of the account statements our customers print off for patients. The new design was pretty heavy and I was going to need to draw a lot of variable-length text that could be aligned to the left, right or center.

We use a library called Zend to generate all of our PDFs, and it has served us well so far. The problem is that all of the previous projects used it pretty lightly and there weren’t any methods written that would help with such a dynamic design. This meant I was going to have to write a lot of the code myself, (which is fine since I am a software developer), but would probably take the project past the deadline our clients were expecting. As the day approached, we began to feel more and more pressure to ship the feature and the code suffered because of it.

The following is a small excerpt from the class responsible for drawing text to the page. Note that the original project was done in php. I’ve transposed it to ruby for the sake of simplicity and because I couldn’t get Pygments to syntax highlight php code nicely.

def drawStaticText(text, x, y, page=0, html_color="#000000", fontSize=0)
    fontSize = (fontSize == 0) ? self.fontSize : fontSize
    getPage(page)

    setColor(html_color)
    self.page.setFont(getFont(), fontSize)

    self.page.drawText(text, x, y, 'UTF-8')
end

def drawCenteredText(text, x, y, page, html_color="#000000", fontSize=0)
    fontSize = (fontSize == 0) ? self.fontSize : fontSize

    width = getTextWidth(text, getFont(), fontSize)
    x = x - width / 2

    drawStaticText(text, x, y, page, html_color, fontSize)
end

def drawRightAlignedText(text, x, y, page, html_color="#000000", fontSize=0)
    fontSize = (fontSize == 0) ? self.fontSize : fontSize

    width = getTextWidth(text, getFont(), fontSize)
    x = x - width

    drawStaticText(text, x, y, page, html_color, fontSize)
end

Yikes, look at that mess! I can see at least 3 things wrong here:

1. Code Duplication

Each of these methods are overly similar. I’m defaulting fontSize in all three, and I’m calling getTextWidth() in the bottom two.

2. Poorly named methods

The names of these methods aren’t consistent, nor do I feel the correctly convey what they’re doing. The person implementing this code might not have a problem understanding what drawCenteredText, does, but it would feel inconsistent next to drawRightAlignedText. And why the word “Static” in drawStaticText? What does that imply about the method?

3. Parameter Hell

There are way too many parameters being passed around here. Some people regard the passing of anything more than 2 parameters to a method as a code smell, and I tend to agree. The more parameters you pass into a method makes it harder to test, looks messy, and generally create brittle code. Sometimes there is no way around it, but you should try to avoid it where possible.

My focus for the remainder of this post will be in reducing the number of parameters being used. self.page.drawText() is off-limits since that’s the call to actual library. Everything else is fair game.

I recently got Martin Fowler’s “Refactoring: Improving the Design of Existing Code”, and it has been an amazing reference for refactorings like this. On page 295, it details the process of replacing a number of parameters sent to a method with a parameter object instead:

Often you see a particular group of parameters that tend to be passed together. Several methods may use this group, either on one class or in several classes. Such a group of classes is a data clump that can be replaced with an object that carries all of this data.

Moving these parameters into an object, and passing it in instead, feels like the right way to go. I should also be able to add the offset calculation required for centered/right aligned text onto the object, and remove that responsibility from the code higher up. I’m still going to have a problem with building the object itself, but I should be able to initialize it with a hash and reduce the chances of it being implemented incorrectly in the future.

class TextObject
    ATTRIBUTES = [
        :value, :x, :y, :alignment, :color, :font_size
    ].freeze

    ATTRIBUTES.each do |attr|
        attr_accessor attr
    end

    def initialize(args=nil)
        ATTRIBUTES.each do |attr|
            if( args.key?(attr) )
                instance_variable_set("@#{attr}", args[attr])
            end
        end
    end

    def x
        return x unless [:right, :center].include? self.alignment
        return (self.alignment == :right) ? calculateOffsetForRight : calculateOffsetForCenter
    end

    private

    def calculateOffsetForRight
        return x - getWidth()
    end

    def calculateOffsetForCenter
        return x - (getWidth() / 2)
    end

    def getWidth
        return self.value.size
        # In reality, this method returns pixel value for the string based on font size / family.
    end
end

You can see that this object is pretty small, and while the initialization looks a little complicated, it makes using it so much easier. I can now go ahead and remove replace all of the parameters with this new object. At the same time, I’ll rename drawStaticText to drawText to better reflect what it is doing.

def drawText( text_obj, page=1 )
    font_size = (textObj.font_size == 0) ? self.font_size : text_obj.font_size
    getPage(page)
    setColor(text_obj.color)
    self.page.setFont(getFont(), font_size)
    self.page.drawText(text_obj.value, text_obj.x, text_obj.y, 'UTF-8')
end

Finally this code is starting to shape up. This is what it would look like to use that TextObject:

my_text_obj = new TextObject({
    :value => "Draw Me!",
    :x => 12,
    :y => 100,
    :alignment => :left,
    :color => "#000000",
    :font_size => 12
})

my_text_obj.x   # => 12

my_text_obj.alignment = :right
my_text_obj.x   # => 4

my_text_obj.alignment = :center
my_text_obj.x   # => 8

drawText( my_text_obj )

I’m sure that there are other ways to refactor this code even further, but this is fine for the purposes of getting rid of all those crazy parameters. Testing the drawText method now should be much easier, and I can write tests for the TextObject as well.

There are still other areas of this project that could use some refactoring, but thats it for at least this section. At least I can browse through this file without having to enable text-wrapping in vim.