Behold the majesty of Archivr!
tl;dr : I inherited legacy code that made my life miserable. Then I learned who the real monster was.
I just inherited my first legacy project. It’s a fun, bare bones web app that takes a screenshot of a URL of your choice. Then you can scribble annotations on the screenshot. It was called Archivr. (“Because adding ‘r’ to the end of a word makes it cool.”)
When I saw it deployed on Heroku, my first thought was that, at heart, this app wasn’t destined to help archivists. It was meant to facilitate people scribbling mustaches and cowboy hats on their friends, major buildings, and the Google search bar. And then sharing their scribbles with friends.
I felt a little bad for my friends who created Archivr. But then I had to suffer through the torment that they – unknowingly – inflicted upon me. I’m here to share my hard won lessons to make it easier for readers about to inherit a legacy project for the first time.
About the Author
My name is Dan Tennery-Spalding. I’m an adult educator-turned-developer here in Oakland. I am enjoying the process of making this silly app because 90% of the time I’m the guy who takes things way too seriously. But what I’ve slowly come to learn is that, before I can build kick ass enterprise-level apps to help Doctors Without Borders better treat injured civilians in war torn regions, I’m going to have build my own developer chops first. And the best way to do that is to just build something that works.
I’m working on Archivr at Hack Reactor, a programming boot camp in SF. I’m on a team with three other junior developers. We all want to do a good job. In fact, for much of the last two weeks, we built our own ‘greenfield’ web app that another Hack Reactor team has taken on as their legacy project. (More on that below.)
Our team kicks ass. Our greenfield app used Angular, Firebase and D3 to allow users on mobile devices to swipe on their touch screens to indicate how they’re feeling at that moment. Our motto was, “Swipe your feelz.”
It was a goofy project. And, in the course of creating it, we all learned how to code a lot better. Perhaps more importantly, we learned how to work together as a team, both in formal roles (with a product owner and scrum master) and informally as colleagues hacking together, day in and day out.
On presentation day our greenfield app worked as promise. We were proud that it worked at all, and, in some ways, even more proud at how easy we made it for the next team to pick up. Our work was (relatively) well documented, our code clearly written, and, due to some serious last-minute rebasing by my teammates, the process to clone and launch it were pretty clear.
Enter the Challenger
One of the reasons we chose Archivr was because it was so well documented. Ten pages of wiki docs on GitHub! And the app itself seemed like a lot of fun. It seemed so well thought out that I actually felt bad for taking it in such a goofy direction.
Then I saw what the original Archivr team did to us.
After that was resolved, there were additional snafus. Conflicting versions of node modules! And more problems we couldn’t even get to the bottom of!
The previous team had also implemented rigorous, continuous Grunt / Travis testing that made it extremely challenging for us to make any changes and see their results. We cursed them on an hourly basis while trying to see what our latest code actually did to the app. For the record, my pal Tole and I struggled with HTML5 canvas technology, coming up with a novel hack using MongoDb and Cloudinary to show both the user’s screenshot (Cloudinary) and the scribble (Mongo!) on top of one another.
My entire body was covered in a fine sheen of sweat on demonstration day. To make a long story slightly longer, we got the app working at the last minute. Our presentation went gangbusters thanks in no small part to my love of public speaking and we were proud of our accomplishments.
So what was the lesson learned? At first, it was that we were the “good guys” who made our code easy to use, while the people we inherited our code from were a bunch of selfish jerks who were incapable of human compassion.
Two complications to this tidy denouement:
1. One of the original developers for Archivr actually gave us clutch help getting the scribble technology to work. (Thanks, Jackson!)
2. The people who inherited our code didn’t find it easy to work with at all. This surprised me because they were up and running and modifying code within hours. (For the record, they also took it in an irreverent direction, turning out mood-tracking app into a mobile game called “Finger Finger Fiesta.”)
But as they described their challenges using our codebase, it all came back to me, like last night’s dream, our fragments of a blacked out night from a friend’s bachelor party in Las Vegas or Thailand: We had multiple files named app.js, a temp.js file I had used as a notepad and never gotten around to deleting (we were on a deadline!) and a number of unused dependencies we never got rid of.
We’re all monsters. We all leave messes for others, whether those “others” are colleagues who inherit our code, members of the open source community who want to use and improve our work, or even ourselves in three months who have to make sense of work that we have already forgotten about.
I’m a better developer because of this experience. I’m already more diligent about cleaning up my code. But more importantly, I have a new perspective on legacy code. I don’t expect anyone to make their work effortless to pick up. Instead, I know that getting off the ground with a legacy codebase will be as much work as developing new features for it.