Originally published on Portuguese in eustaquiorangel.com/posts/ambiente_minimo_driver_driven_development
Some weeks ago I had an experience on a Ruby on Rails project where I found a curious situation and made an interesting analogy to the project owner. I'd like to share it with you.
Imagine we are working with auto mechanics. All cars have similar characteristics, like having 4 wheels, engine, doors, etc., with some with very peculiar characteristics. On this analogy, cars are software projects, and as we are good mechanics (developers), we know how to handle the common features and some of the most specific features.
Then there comes a person and says that there is a car parked in the garage for some time, and asks me to replace its alternator, which has been defective. The alternator is a specific project feature. He needs this part changed ASAP, okay, let's see what I can do.
I ask for access to the garage, which is the code repository. The person opens the garage for me and I push the car, which is covered by a tarp, out (clones the repository) of the garage. Until that moment I have no idea what kind of car it is, until I take a look under the tarp (reading the project files). I remove the tarp, okay, things are apparently in place, it's a car, after all.
Only then I notice there are some things missing. There are some fuses (talking about a Ruby on Rails project, the
database.yml) not in place, and without them, no chance of turning on the engine. Luckily I have some spares and I just need to ask the customer if he remembers how many amps it was (the production configuration, which are on environment variables, ok). I notice that there are some very old pieces that I do not need anymore (the therubyracer gem), then I remove it and connect the wires directly, making it works (node is installed, so, it works).
Then I remember the person mentioned that there was a missing part in the car (an external private repository that no longer exists) and that she had the piece at home (a copy of the repository code). I go there, get the piece (using a usb stick) and put it in place.
Then I try to open the car, but the key (login data) I got was broken (log in the system didn't work, the login data is wrong). I try to look for the spare key, and find the specs of three spare keys, where each one opens the car but changes the panel layout, which although old, is digital, for layouts I have never seen, specific to that specific car (custom layouts with a lot of menus and features). As none of these keys exist, I just have their specs (characteristics of each user, which I found in the code), I turn on the lathe to build the keys using the specs (feeding the
seeds.rb file). Now, with the keys, I can open the car.
The car has fuel but lacks oil, brake fluid and a lot of missing things needed to make it work properly. I spend some time looking at the specifications in the car manual (reading the models files and data needed to log in) and some time later I can fullfill all those needs. I had asked the person to send me the missing pieces (the database dump), but she was without transportation (no internet where she was), so I had to do it myself. Whatever.
I open the car door, turn it on, the first key panel lights up, with a lot of custom options I've never seen in my life (but I've finally logged in, yay). Ok, some are basic, but most, I do not know, I'll need to take a look at how they work and what they are used for.
Now I can finally concentrate on the most important task that has been asked to me: replace the alternator with a new one. I have 2 options:
Replace the current alternator with a new one, which is a different model, and ask the car owner to take a ride with it. This way might leads to some kind of trouble, with the car turning off, catching fire, blowing up, or some other kind of calamity, because I did not diagnose the car after replacing the old part, I just know it started working.
Connect my laptop to the car computer (the test suite, hey, there was a test suite, that's good news!) and check if everything is working with the new part. But then I find out that of all the features available for testing, almost 50% are failing! This generates a lot of noise even if I focus only on the alternator related tests. I ask the person if the computer has some defects and if I can isolate all those tests failing to avoid generate noise in the diagnosis of the new part, and make clear that is very important to check later why were those tests failing.
I wait for an answer, as well as comments on the other things that are being done, but it takes a while and the end of the day is coming. Better put the car back in the garage and wait for an answer. Then I find that the person closed the garage lock and took the key away (I don't have write permissions on the code repository). Then I put the car on a garage I have near there (I make a fork of the repository) just to make sure it is safe. To avoid forget all the details of this saga, I put some notes on a small notebook (the README file).
As I already commented in a previous article, it seems that I took an example of "code taste", that is, working code, but working only on an environment already configured to fit its needs, ie, on the computer of who developed it and kept it there for months, running without deleting its code, so deep-rooted that it almost developed a peculiar taste, like a hamburger grill you often forget to clean. There was already a
database.yml file configured, the database was filled with all the needed data to log in, there was a lot of code tweaks, changes (like commenting the external repository) and enviroment variables that make the project works only on that computer.
But as a new person involved on the project, to simply run the server and log in, I needed to do all those tasks, and it took me hours to do that, as well as any other newcomer person who eventually needs to work with the project and don't have support from a person who knows it very well. Once I heard a college professor say that good documentation or book does not need the author attached with it, and I agree. We need good documentation, more expressive and organized code.
The Ruby on Rails framework gives us all the conditions to do those kinds of things, allowing who has access to the code to run the project locally in a very easy and fast way, if you follow certain conventions (hey, "convention over configuration", after all) and practices, for example, properly feed your
seeds.rb file, create a README file with specific information and instructions to run the project and keep your test suite in a working state, allowing it to run, allowing it to run fast, and better yet, allowing who needs to be involved on the project to read your tests and understand how the project behaves.
As we did here, think on the project like a a car. The only thing you need is to give the garage key to whoever you want to open it, find the car keys over the car hood, open the car door, start the engine and drive. Simple. If it takes more than that to drive the car, maybe is a good idea spend a little time organizing things. Focus on the driver who will drive the car, that is, the developer who will work and run your project. Make things easier for the driver, even if the driver is you.
I’ve sent a message to my family and delegated my open source projects to my friends. With my last tweet sent, I turn off my laptop, phone, and tablet. My Digital Sabbath begins in 10 minutes: no digital devices for the next month.