Hunting Bugs or: How I Learned to Stop Worrying and Love git bisect

Getting assignments to write new features on a web app is always way more exciting than looking at Pivotal Tracker and seeing a list of bugs to fix. But I have to admit that probably the most satisfying feeling as a programmer is the feeling you get when you’ve solved a complicated bug in a clean way. I’m not talking about bugs that are caused by syntax errors or accidentally using the wrong methods. I’m talking about the bugs that have seemingly innocuous symptoms, but end up taking you deep into the rabbit hole of your app.

The work here is the hunt — once you’ve actually tracked down what’s causing the problem, it’s generally very easy to fix the issue. When you’re working on a large codebase with multiple contributors for an asynchronous web 3.0 app, this can get really interesting (and frustrating). What do you do when the problem isn’t immediately apparent?

About 25% of the time, you get lucky and Google does all of the work for you — simply copy and paste the error message that the application is giving you or type in a short description of the issue and you’ll be surprised how many people have encountered the same problem and have solved it already. Stack Overflow is a goldmine of bug solutions, and so is the vast ecosystem of tech bloggers (like me) who give you step-by-step instructions on how to solve bugs.

70% of the time, it’s a bit more of a challenge. The bug is specific to the way your team has set up the application and no one has encountered a bug quite like the one you’re currently facing. Google doesn’t help at all. Here’s where bug-hunting becomes much more of an art than a science.

Typically the process is fairly quick if you’ve written the code that you’re debugging — you already know what assumptions you’ve made in developing the feature and what events are firing when, and so strange behavior can often be tracked down fairly quickly. Luckily, you’re using git (right?), so even if you didn’t write the code you’re working with, you can quickly track down who did. Simply run git blame path/to/file in your console and git will output a line-by-line summary of who wrote each line of code.

If that doesn’t get you closer to a solution, the next step is to console.log (or its equivalent) everything. I’ve had the opportunity to see expert programmers hunt down bugs at, and that’s exactly what they do. There’s generally no need to use fancy debugging software or set breakpoints or anything complicated like that — just output to the console when events are firing, when methods are being called, and what the value of variables are at specific points in time. Obviously, you need to make educated guesses as to what might be causing the problem, and then figure out whether you’re right by outputting values to the console.

What about the last 5%? It’s reserved for the worst kind of bug. The bug that is impossible to fix. You’ve searched all over the internet and no one seems to ever have had the same problem. The code you’ve written and poured over is perfect and definitely is not the cause of the problem. The project you’re working on has thousands of lines of asynchronous code — literally anything could be going wrong and you have no leads whatsoever. Don’t worry, there’s still hope. git bisect is still your friend.

git bisect works when you know that a feature worked at one point in your app’s history and no longer works in your most recent commit. Don’t know offhand when the feature actually worked? git blame can help here — find out when the feature that’s no longer working was merged into master, and you can hopefully safely assume that the feature was working at that point.

Once you’ve located a good point and a bad point in your code, run git bisect start in your current branch. Then, since a git repository is basically a sorted list of previous states of your app’s codebase, git can perform a step-by-step binary search to find the first point in your app’s history where the feature stopped working. At each step, you run either git bisect good or git bisect bad in your console depending on whether the feature works or doesn’t work in the commit that git bisect picks. Eventually, the program will output the commit id of the commit that broke the feature. It’s an amazing feeling when you’ve been struggling with a bug for a day or two.

git bisect isn’t always that simple when you’re running it on an app that has a bunch of dependencies. Here’s how to get around any snags if you’re running git bisect on a rails app:

  • Restart your rails server and run bundle install at each commit that git bisect chooses. You might also need to manually compile assets at each point if something isn’t doing that for you automatically.
  • Make sure your “good” starting commit is the commit that merged the feature you’re debugging into master. Programmers don’t always commit 100% working code, but when it comes time to actually merge a pull request, you can be sure that the app ran smoothly and specs were passing.
  • Sometimes the app won’t run on old commits because paths in old versions of your Gemfile aren’t valid anymore. For example, when I used git bisect on’s codebase, a co-worker’s change to his Github username caused multiple bundle install failures. You’ll have to address these issues manually. If you can’t figure out why a gem isn’t installing, just replace the line with the corresponding line in the app’s most recent Gemfile.

Aside from those potential issues, git bisect feels like magic for those epic bugs that refuse to be solved. Once you’ve found the commit that broke the feature, you’re almost certainly 99% of the way to solving the problem.


Building Site Navigation with Markdown and Nokogiri

Who knew that Markdown — in my opinion the best text-to-HTML syntax available — could be used for something other than blog posts (or Github readme files)? Turns out that Markdown can be used as a powerful way to make web app navigation really simple to edit, even by non-developers. The task I set out to do was to turn something like this:

* Home
* About
    * About Us
    * API
    * Terms of Use
* Browse
* Etc.

into a nice dropdown menu. Making this markdown text available to a view is a fairly simple task. In Ruby on Rails, if you have a Page model that can hold Markdown text, you simply have to fetch it in the controller and call .to_html.html_safe on it. Also, with the help of some ternary operator elegance, you should make sure that if the page doesn’t exist, the code doesn’t blow up.

c_nav = Page.find_by_slug 'client-nav'
@client_nav = c_nav.nil? ? '' : c_nav.to_html.html_safe

So now, with the addition of a simple line in the view where we dump the contents of @client_nav onto the page, we’ve accomplished displaying a terrible looking unordered list when we could have just hard coded a nice looking menu in Haml. Here comes the fun part.

The obvious first choice for this task was to use jQuery to dynamically add CSS styles to the unordered list to turn it into a nice navigation menu. With the use of jQuery’s addClass method this is fairly simple, and it worked when I implemented it with just a couple lines of code. Unfortunately it resulted in annoying flickering as the page loaded because the unordered list is displayed un-styled for a split second (unacceptable). This could probably be fixed, but why bother doing something on the browser when it can be handled perfectly well on the server? After a couple of painful hours attempting to add classes to the generated HTML using Ruby string manipulation techniques and having little success, I discovered that this problem had already been solved by the creators of the Nokogiri gem.

To begin turning the raw HTML into styled goodness, I first stripped out the opening and closing ul tags manually. I enclosed the code to do this in a beginrescueend block because the test suite I’m using (Rspec) didn’t like me using negative numbers for indexes in a string for some reason.

   @client_nav[0..3] = ""
   @client_nav[-5..-1] = ""

Then I let Nokogiri work it’s magic.

@client_nav = Nokogiri::HTML::DocumentFragment.parse(@client_nav)
@client_nav.css("li:root").each do |anchor|
   anchor['class'] = 'nav_item'
@client_nav.css("li:has(ul)").each do |anchor|
   anchor['class'] = "nav_item more"
@client_nav.css("ul:first-child").each do |anchor|
   anchor['class'] = "dropdown"
@client_nav = @client_nav.to_html.html_safe

Because the HTML I was passing to Nokogiri is just a fragment of an unordered list, I used the DocumentFragment.parse method to prepare the HTML for Nokogiri to dynamically add CSS. Then, using basic CSS selectors (as well as one really useful one — has() — taken from jQuery), I added the proper classes to the list elements. It worked like a charm.

I’ll leave the CSS magic up to you — suffice it to say that with the proper stylesheets, this can look really great and is infinitely configurable. Why bother with bulky client-side code when Nokogiri provides a just as (perhaps even more) elegant solution?

Tag Clouds in Ruby on Rails

Tag Cloud
My finished tag cloud.

One of the first projects I got to work on at was a tag cloud that provides a quick visual representation of the types of artworks that are in the site’s database. These can be quite visually striking if done correctly, but can be ugly if done poorly. Some of this is a result of design considerations (the underlines on the second tag cloud aren’t helping) which is definitely not my area of expertise, but the algorithm behind a tag cloud is just as important if it is going to be successful.

Just like any good Ruby on Rails/jQuery developer, I first scoured the internet to see if someone had already solved this problem adequately. What I found wasn’t too promising — many of the plugins were using math that would output text in just a couple of preset font sizes, and wouldn’t fully capture the relative frequency of a given tag. I determined that I would have to build it myself, and because at the time I was much more comfortable with Ruby than I was with JavaScript, I decided that I’d build the logic into the backend rather than build a jQuery plugin. I did get help on the algorithm, however. The best one I found was the following (which I’ve translated into Ruby):

weight = (tag.count-minOccurs).to_f/(maxOccurs-minOccurs)
size = minFontSize + ((maxFontSize-minFontSize)*weight).round

For the code above, minFontSize and maxFontSize are constants that you decide beforehand that dictate the font sizes for the least occurring and the most occurring tag. For my purposes, a min font size of 5px and a max font size of 100px worked nicely. minOccurs and maxOccurs need to be determined algorithmically before running the above code (this is quite easy for my setup, and we’ll see). The way this code works is slightly cryptic, but basically it first determines a ratio of how much the tag differs from the lowest tag relative to the entire span of tag counts, and then uses that ratio multiplied by the span of font sizes to determine how much greater the font size should be for a given tag above the minimum font size.

The rest of the code isn’t too difficult, but took a while for me to configure correctly. To start, it’s a little unclear where exactly this code should go. I initially created a tag_cloud method in the Tag model, which I then called in the controller to pass to the tag cloud view, but that doesn’t really make sense because the logic here has to do with font sizes and other visual considerations and thus shouldn’t be in the model. I ended up putting all of the logic in its own method in the tags controller.

def tag_cloud
   tags = Tag.asc(:name)
   if tags.length > 0
      tags_by_count = Tag.desc(:count)
      maxOccurs = tags_by_count.first.count
      minOccurs = tags_by_count.last.count

      # Get relative size for each of the tags and store it in a hash
      minFontSize = 5
      maxFontSize = 100
      @tag_cloud_hash =
      tags.each do |tag| 
         weight = (tag.count-minOccurs).to_f/(maxOccurs-minOccurs)
         size = minFontSize + ((maxFontSize-minFontSize)*weight).round
         @tag_cloud_hash[tag] = size if size > 7

All I’m doing here is storing the tag objects and their calculated sizes in a hash to send to the view. I’m excluding tags from the hash with calculated sizes less than 7 for purely aesthetic reasons (there were a ton of tags, and having all of them in the tag cloud didn’t look great).

The view code, written in Haml, is even more straightforward.

   Most Frequently Used Tags
- if @tag_cloud_hash != nil
   - @tag_cloud_hash.each_pair do |tag,size|
      .cloud_element= content_tag(:a,, { :href => "#{tags_path}?tag=#{tag.slug}", :title => "#{tag.count} artworks", :style => "font-size:#{size}px;" })

Actually, the part of this project that took the most time were the stylesheets, mostly because I find CSS in general to be really counter-intuitive. It’s always unclear to me what styles are being inherited when I’m working with large stylesheets. Luckily, I’m writing the styles in SASS which helps a lot. Here’s what I came up with:

   display: block
   width: 600px
   margin-left: auto
   margin-right: auto
      text-align: center
      display: inline
         text-decoration: none
         line-height: 110%
         vertical-align: middle

Put all of this together and you get a pretty nice looking tag cloud. There are of course tons of possible improvements, and it still looks nothing like my example of a well done tag cloud, but this is a good start and is a big step up from a lot of the tag clouds I’ve come across online (including the one on this site). If I ever come back to this project to improve it, I’d probably redo it in jQuery rather than keeping the logic on the backend. While writing the code in Ruby was (I think) much more elegant than a potential JavaScript solution, moving to frontend code would open up the doors to tons of fancy effects. And fancy effects are cool.

The Beginning

I’ve been a “liberal arts person” my whole life. For most of my academic career, I have identified English and History as my favorite courses. But oddly enough, Physics class turned out to be the most interesting class in high school, and BC calculus was my favorite class in the Winter term of my freshman year in college. I realized that this interest wasn’t isolated for the last couple of years — in my spare time, computer programming has been a hobby of mine since sixth grade. It’s taken me 8 years to realize that I actually love applied math, especially when it results in a cool video game or a groundbreaking website. About two months ago, in the middle of the first academic course I’ve ever taken in computer science (Intro to Java, of course), I realized that I had to pursue this discipline more seriously. I had way too much fun at school last term to not continue with computer science.

Since then, I’ve thrown myself headfirst into the tech world. Over the past two months, I’ve created a Twitter account (@mmcnierney), joined Hacker News, and created a GitHub account. There are probably more — I can barely keep track of it all. Oh yeah, there’s this blog too.

The best part of it all is I’ve had the incredible opportunity to intern at this summer, a start-up based in New York City that wants to be the Pandora for the art world and has some serious potential to shake up the fine art industry. Over the past month, I’ve gone from knowing very little about Ruby on Rails and jQuery, not to mention never having heard of git, Backbone.js, Haml, SASS, or MongoDB, to having a fairly solid working knowledge of the “bleeding edge” of web development. Just as exciting has been all I’ve learned about start-up culture from working in General Assembly, which has turned out to be the greatest work environment imaginable, as well as all the lessons I’ve had in managing tech teams from both the founder and the head of engineering. More on that later.

I’m at the very beginning of what I hope will be a long career in this industry, and I want to record all that I’m observing and learning. I’m going to be documenting the programming challenges I’m working on, because the more I learn about open source the more I want to contribute back to the community that has given me so much for free. But I’m also going to be commenting on start-up culture and the more intangible things I’m learning, while talking about the projects I’m working on and what I’m doing during the school year to stay connected with this incredible tech world that I barely knew existed until very recently. I intend for this blog to have something for everyone, so enjoy! I know I will.