Rendered Text

Doing code audit before improving software

2012-02-22T00:00:00-08:00

Recently we received a request to analyze and improve a process in a Rails app which consisted of half a dozen rake tasks. While our standard practice is for a rake task to consist of a single line, usually a class method call that’s properly spec’d, these rake tasks had from 40 to 120 lines of code and almost no test coverage.

Making a correct estimate can be very difficult, sometimes even more than the actual coding, but when you are faced with code that’s full of smells and no tests, it’s practically impossible without a thorough analysis and even writing some meta code.

For starters, before any attempt was made at improving the code and making it more reliable, we were aware that we first needed to refactor. Martin Fowler defined refactoring as “a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior”. But why refactor when the rake tasks were already working? Why not just add or update a method? It’s simple. To begin with, it’s it was impossible to responsibly extend the code as it was. Refactoring allows us to more easily read, understand, update the code and write tests for it. Also, when the code is well written, it’s far easier to accomplish proper benchmarking and profiling.

Tools that we used for the analysis were:

a pen and a notebook
GitHub and it’s Gist feature
WorkFlowy and
Pivotal Tracker

Our workflow was pretty straightforward. We would use the pen and paper to better understand the current code by drawing sketches that visualized the various interactions in the process. After that, we would go line by line and whenever we saw a piece of code that was a candidate for refactoring, we would mark the corresponding lines on GitHub and reference it on WorkFlowy with a short message of what needs to be done. If we already had some meta code in mind, we would write a Gist containing the meta code and attach it to the message.

We decided to first just address the more standard code smells (long method, long parameter list, duplicate code, uncommunicative name…) and later on, when we start with the actual optimization, address the more complex smells that have to do with code structure and system architecture. Majority of the planned refactoring involved moving out pieces of code into a method or a class.

Our goal was to eventually be able to pull out the process into it’s standalone application, which would just send processed data back to the main application. With that in mind we tried to place most of the code into the ‘lib’ directory and make it as independent as possible.

Once we had a WorkFlowy list, which gave us a hight-level overview, we were finally able to create Pivotal Tracker stories and to give a time estimate.

Here are a couple of books that I found very useful when I was learning about refactoring:

Nebojsa Stričević joins Rendered Text

2012-02-20T00:00:00-08:00

We welcome Nebojša Stričević as the fifth member of Rendered Text, after completing a trial month in our office. Since he sent us a letter, beautifully typeset in Latex, we’ve been impressed with his capacity to focus, learn and solve new challenges. He’s both self-managed and a good team player.

We’re happy to have achieved nice growth in the past year, and believe that our new capacity will allow us to execute ideas for an even better one - some of which you will hear about here soon.

Beware of MongoDB's document size limit

2012-02-17T00:00:00-08:00

As a MongoDB beginner
When designing a database for large quantities of data
Then I should be aware of the document size limit in BSON format

Including all embedded documents, it is currently 16 MB per document, unless you’re using GridFS (but it seems like if you can’t get GridFS from 3rd parties like MongoHQ or MongoLab?). Remember that MongoDB by default puts the working set of your database in RAM.

So if you expect to have millions of some things then you better put those things in a separate collection, even if semantically it may make more sense to embed them in another document. If you’re using mongoid that simply means having a stand-alone model referencing another model.

Useful discussions on Stack Overflow:

My short trip to India

2012-02-14T00:00:00-08:00

The short part is a bit tongue in cheek since to most people 25 days sounds like a long trip but for India, it’s just too short.

Everyone I’ve met that has been to India has had a unique experience. I went with a couple of my close friends, my best friend already there for three months, finishing his internship. We landed in Bangalore and planned to fly back from Delhi.

India is the first place where I’ve experienced the feeling of almost too much freedom. You feel a certain connectedness with nature. Partly because animals freely roam through the streets, even in very urban places like Mumbai, and in part because you see an incredibly diverse and almost untouched, nature. Hampi, which is my favourite place of all I’ve visited, is like that. Like God made a bouldering place for for himself. If you climb, you must visit it.

Me in Hampi

But India is a land of contrasts as everyone will tell you. You see the extremely poor people and the extremely rich not more than two blocks from each other. Some of the former you can see living in slums and the latter in fort-like mansions. In spite of that, it seemed to me that the (not so rich) people in India are really happy. We had a running joke if were going to stumble upon anyone who’ll treat us badly. But now that I think about it, a woman in Jaipur carrying bamboo sticks pulled out the largest knife I’ve seen when I tried to photograph her.

Indians work a lot. Much more so than people in Serbia or elsewhere I’ve been. So many people work Sundays that you just don’t care which day it is anymore. I tried to get my films developed on Sunday, January first, but the guy in the neighbouring shop told me that the photo store is closed on Sundays. Working on January first was the usual deal for him. It’s not that it’s mandated that you should be open, it’s that by being open you get to earn money that day.

A boy running a masala chai stand in Pushkar

It seemed to me that there’s a kind of entrepreneurial spirit everywhere. Something is happening all the time around you. People are offering you things, fixing things, painting their shopfronts or otherwise making their shop more noticeable in streets packed with small shops. In a Mumbai bookshop you can see a lot of REWORK copies and that ‘The Lean Startup’ is currently one of the best selling titles.

There’s a feeling that there is a free market system in effect on the street level. You go to a rickshaw driver and haggle over the price and sometimes you get to pay less than the meter and sometimes you pay more. I’ve heard that Indians get offended if you don’t haggle, but to me they seemed very happy to see you pay much more than you should. And why wouldn’t you do it when it’s so much fun.

I really miss India.

Sucking less at writing Cucumber

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

I wrote my first Cucumber scenario about five months ago. It went something like this:

Scenario: Changing email
  Given I am logged in
  And I am on the homepage
  When I click on "Account"
  And I fill in "email" with "milos@example.com"
  And I press "Change Email"
  Then I should see "Email successfully changed"
  When I visit "My profile page"
  Then I should see "milos@example.com"

Maybe my naivete was not solely to blame; I was told it was so easy “that it could be taught to a secretary”. I am not so sure anymore.

Some of the problems with the above scenario are:

It’s too long and verbose
It’s not using the domain language

Read the scenario. As a reader, why do I need to have a mental model of that web site to be able to follow it? Couldn’t it be replaced with:

Background:
  Given I am logged in

Scenario: Changing Email
  Given I am on my account page
  When I change my email
  Then I should see that my email has changed

Using web steps makes you write very imperative scenarios that you have to rewrite each time you change something. It’s actually one of the reasons why they were removed from the latest version of cucumber. People used them too much and wrote shitty scenarios. I’m not sure I agree with the descision to completely remove them but I can undestand. The pull request now serves as an explicit note that you should be writing declarative steps.

A good indicator that your scenario is not good is if you change something in your implementation and you have to change the scenario. You’ll probably need to change your step definition anyway but the Gherkin stuff should be as decoupled from the implementation as possible. In the above scenario:

How I change my email is an implementation detail and belongs in the step definition
How I see that my email really changed is also an implementation detail

We still test if this whole system works but if I change how it works I only need to change the step definitions. The scenario stays the same.

Lately I just write the whole scenario and implement the steps. I only reuse steps if I see that the one I had just written is similar in wording to some step I had written before. The added benefit of this is that I now know capybara much more intimately than before. Capybara is very powerful and much nicer to work with than web steps.

Reposted from Miloš’s blog.

Agile and change

2011-11-29T00:00:00-08:00

It happens that people identify themselves with a piece of work that they did. From a purely logical perspective, this does not make any sense, and generally it is a guaranteed way to lose your personal tranquility. Yet it’s sometimes difficult to control, especially if you don’t practice it somehow.

To a programmer it may occur on both code and feature level. You think that something is such a great piece of code that it’s a pity to remove it. The more time you’ve spent on it, the greater the feeling. It influences your thinking in a situation when you’re asked to discuss the real user value of it.

That’s one aspect where agile shines. When you’re writing a spec first, that flow has framed the implementation code for you differently. It is more like a means to an end - to make the nice test pass. And that’s good because your code is a means to a user’s end. So you’re not personally attached to it.

And when you’re collaborating with your client daily, he gets to see the direction where you’re going with a larger feature when it’s 20% done and not 99% done. It’s a great framework of collaboration where nobody is afraid or opposed to change for any reason. Indeed, you will embrace change, as change is natural and feel a boost every time you refine your creation to better match the product.

Apprenticing at Rendered Text

2011-10-21T00:00:00-07:00

I’ve kinda fell in love with Ruby after several love affairs with different languages. Somehow it just felt right both for reading and for writing. So I’ve set out on a mission to write a lot of Ruby code over the summer. Luckily, the guys from Rendered Text needed help of an eager new rubyist and I needed a place to work with Ruby so that I can “get it into my fingers”. I was really excited because I knew they weren’t locked in into some old legacy software system but were open to whatever works, new or old. I also knew they were into software crafstmanship which is a movement in software development that I really like.

Tortured apprentice

Since I live in Belgrade and the Rendered Text office is in Novi Sad, the deal was for me to work remotely and occasionally go to Novi Sad for a few days. I had my first week in Novi Sad, mostly pairing with Darko.

Pairing

In the first week, I paired with Darko on some Ruby code. I was happy that it was pure Ruby and not Rails because at the time my Rails knowledge was rather weak. I’ve only just read The Ruby on Rails Tutorial book and I thought that I would be useless as a pilot or copilot. That turned out to be wrong and I was surprised to actually be useful. Maybe if it were Rails code I would have done worse, but probably not that much worse. Even if you don’t know the code, you’re still useful in a pair programming session because you review code and ask questions about it as it is written.

Pairing is also a great way to pick up editor and workflow tricks. I know I’ve picked up quite a bit of vim and git tricks from Darko. I think he got a few from me as well.

Code reviews

We use GitHub’s pull request feature quite a bit. Most of the time when I wrote a piece of code that isn’t trivial, I would open a pull request and either Marko or Darko would review it. This is by far where I learned the most. Writing some code the way I think it should be done and then getting detailed feedback on how it can be done better is invaluable.

Reading

Before I even started I needed to get up to speed with the tools used at Rendered Text, mainly RSpec, Cucumber and Rails. Marko and Darko suggested The RSpec book and The Ruby on Rails Tutorial. To this I would add Apprenticeship Patterns. I probably should have read it earlier in my apprenticeship.

I wanted to read as many books, articles and blog posts as I could, but there’s only so much you can read in two months. It’s great to be able to discuss what you read right away with people who have way more real world experience. Especially as I got interested in object-oriented design. I would come in and try stuff I read about in a blog post or a book and could get feedback or even a discussion going.

BDD

Pretty much everything done at Rendered Text is developed using Behaviour-Driven Development. I was already sold on TDD before I arrived but I needed to acquire a taste for writing acceptance tests with Cucumber. At first I really sucked at this. It was hard for me to write good scenarios. Fast forward a few months, I still suck at it but a little bit less. An area to improve I guess. Reading the RSpec Book’s chapters on Cucumber helped. I’m planning to read through the new Cucumber Book, and I hope that’ll help as well.

Working remotely

While it was super nice to work at the Rendered Text office, most of my work time was spent at home. We use Campfire quite a bit and also Pivotal Tracker and Basecamp. Campfire is super cool, kind of like irc on steroids.

Tools aside, working remotely has some benefits but also some not so trivial downsides. The biggest benefit is that you don’t have to commute to work. The biggest downside is that it’s sometimes much harder to “get in the zone”. Pomodoros can help with this.

What I did wrong

I think the biggest mistake I made was not reporting that I was stuck soon enough. Several times when I couldn’t do something that I assumed was simple and that I could “figure out”, it turned out to be far from reality. I would spend a lot of time without anything to show for it. To make matters worse, it was usually something that would take a few lines on Campfire to resolve. In hindsight I really should have asked for help as soon as I got stuck. Asking on Campfire isn’t as attention stealing like tapping someone on the shoulder and If someone knows it, you usually get an answer pretty quickly. If it turns out you can figure it out yourself, you just update the Campfire channel and there’s way less time wasted.

Conclusion

This was so far the nicest part of my working life. I’ve learned a lot, had quite a bit of fun and met really nice people. I’m also very happy that I’ll continue to work for Rendered Text.

To any aspiring software crafsmen, I cannot recommend apprenticing highly enough.

Making change

2011-10-18T00:00:00-07:00

From Individuals and Interactions: An Agile Guide:

When building a new system, the software developers’ livelihood is based on creating change. At the same time, the world of many users of the new software may resist having to learn new tools.

While we, hackers, are all proud to be makers, it’s easy to forget that in the end anything we make is a change for everyone who’s exposed to our work. It is probably an underestimated reason why most software projects fail - they simply fail to negotiate enough attention with users.

Every time you decide to use a piece of software, you enter an unwritten contract, where the application promises to be useful for certain tasks that are important to you, while you promise to give it your time, attention, and a spot in your living habits.

It is no wonder that everyone sooner or later optimizes to work with less software. That is actually the starting point for most people outside the technology world - and they never move from it. We often need a number of years to enter that zone, and we may even glorify that realization, as shown by the popularity of software blogs that talk about “minimalism”, “simplicity” and “zen”.

Similarly, on the web, “tools” are replaced with “web sites” and the concept remains. We have just enough space in our brain to visit a few sites when we’re online, and it why most people get most of their information via recommendations off very few social web sites.

That would mean that most web sites should be optimized for casual, short interaction and a short attention span. Be useful, and provide for quick exit. For a user it’s a happy loop, and it’s a promise for an eventual return.

How to solve the losing X11 connection problem with VirtualBox on Mac OS Lion

2011-10-17T00:00:00-07:00

We all know that today you cannot get a better desktop operating system than Mac OS. Together with great Apple hardware the bundle is an unbeatable desktop platform. But everybody in our team has been sailing with Linux for almost a decade and we still prefer it as a development platform. Paired with isolation that VirtualBox provides we just feel like at home in our Linux + VirtualBox development boxes.

Since we upgraded to Lion we got scared for a sec that we will have to leave VirtualBox + Linux behind because we just couldn’t solve an issue of losing X11 connection, which is of corse key for running Cucumber scenarios that require Firefox. After googling about the issue for 5th time we found a solution which is extremely simple and works well for us. You just need to add -Y when you are ssh-ing into your development box e.g. ssh -Y devbox.

Solution is documented in a message on Apple discussion forum – https://discussions.apple.com/message/16025066#16025066. Although some people reported that they still have some issues we haven’t experienced any of them.

admin_view 0.2.0 released

2011-10-17T00:00:00-07:00

It happenned on Friday, but I had to postpone blogging until now – admin_view 0.2.0 is out and features new options: --no_create and --read_only for cases when the admin should only browse through user-created resources and a couple of improvements to code generation. A big thank you to all the people who tried the gem and were kind to report issues that they’ve had.