Imagine you’re about to sit down and begin working on a new feature for a 10-year-old project. You’re excited, because the older project has proven to be a huge success in the market, and it feels great to contribute to something we know others find valuable. Your time is not going to be wasted.
…Until it is, as you spend three days trying to get the dang project running on your computer! In frustration, you begin to curse the name of the villain who set up the project, and then the horror hits–you were that villain! What was obvious 10 years ago is now lost to the sands of time.
No one wants to spend more than a few minutes getting started on a new project. Here are three tips to ensure that standing up a project is a positive experience.
1. Capture project setup as executable code.
In the same way that we use tests to capture requirements with executable code, we can capture project dependencies and setup with code. Does it take several commands to acquire the source code, install dependencies, compile the application, and run the tests? Start out by capturing that in a small setup.sh script or the like. Ready to get fancier and more sophisticated? Look at tools like Vagrant and Chef to create dedicated development environments.
The capybara-webkit project includes an excellent example of setting up an environment via Vagrant.
2. Document the “why,” as opposed to the “what” and “how.”
Documentation is often centered around “what” and “how” the system works. That can be handy, especially when it’s written as a high-level overview. But ultimately, both the low-level details and the high-level overview can be reconstructed from the code and behavior of the system.
What is much, much, much more difficult to reconstruct is the “why” behind the behavior. This often comes up in exceptional cases–why are we branching here? Is it because of a business rule? Ten years later, does that rule still make sense? If not, let’s remove it and reduce our maintenance burden. Or was that branch there to work around another bug? Oops…better not remove it then!
The Node.js project’s node_file.cc file has a great example of this–the comment above the InternalModuleState function reads, “Used to speed up module loading…The speedup comes from not creating thousands of Stat and Error objects.” Were it not for the comment, I might come along later and think, “Hmm, this look redundant with the other function, so let’s remove this one,” which would be a naïve thing to do.
3. Think from the perspective of your future self.
I find the best advice of all is to consider my future self. What’s going to be important to me a year from now? Solving new problems or old problems? That’s a rhetorical question–you know the answer.
I often remind myself of the title of Steve Krug’s classic book Don’t Make Me Think. What breadcrumbs can I leave myself now to avoid thinking and redoing work later? Here are some examples:
- Automating project setup and/or authoring a “quick start” guide to get going quickly.
- Writing notes about why a final decision was made and/or why a feature is implemented in a particular way.
- Locking version numbers for your application’s dependencies, as new versions may change behavior.
- Archiving dependencies, in case they disappear from the internet.
- Drawing a medium-high level picture of the system so you have a visual reminder for next time.
You’ll see that the first two items in the list above correspond to the first two tips in this article–they are aspects of considering your future self.
In conclusion, it’s worth noting that all of the above advice, especially the last tip, will benefit others as well as yourself. People will greatly appreciate it when they can take advantage of your automation, notes, and breadcrumbs in the future.