2. Golden Rules (for Projects and Programs)¶
The goal of this chapter is to give you a set of rules, guidance, and some hard-earned wisdom to help you write better programs and develop better projects. You’ll code faster, the coding will be easier, and it will result in code that is easier to understand, maintain, scale, debug, and repurpose.
I’ve spent more hours of my life fixing bad programs and issues caused by project management mistakes than I have spent watching the Detroit Lions be awful. So, please, let me help you avoid that tragedy! Don’t let the Lions OR bad project/program habits ruin your Thanksgiving!
It turns out that these issues are not unique to me. Economists, financiers, social scientists, and researchers that are trained outside of software engineering or computer science are often (especially early on in careers) unaware of solutions those fields solved for problems that social scientists are only now (at least to them) just facing. It’s very common, for example:
You can’t replicate an early version of analysis because it calls functions that have been moved.
You want to change your sample for tests #4-#12 (in an analysis with 15 tests), but the code that defines the sample has been copied and pasted throughout our project directory, and making the change requires updating dozens of files. Turns out, there were copy-paste errors, so those tests didn’t even use the same sample!
You return to a project after weeks (or months…) (or years…) away. Despite all the documentation and comments you left behind, it takes days just to figure out how to run the analysis again.
I love this line from a document this part of the textbook is heavily based on:
Here is a good rule of thumb: If you are trying to solve a problem, and there are multi-billion dollar firms whose entire business model depends on solving the same problem, and there are whole courses at your university devoted to how to solve that problem, you might want to figure out what the experts do and see if you can’t learn something from it.
Most of the time, your code will be read by other people (e.g. future you). You’ll need to run it again, or change it. Skipping the tips in this chapter will make that much harder to do and cost you lots of time. If you don’t value your time in the future (high discount rates), you might want to ignore this chapter. BUT! Here’s the thing: These tips make writing your code faster the first time you write it!
Let’s start by looking at a project that doesn’t abide by these hard earned wisdoms…
Credits
This chapter leans heavily on the wonderful Code and Data for the Social Sciences: A Practitioner’s Guide by Matthew Gentzkow and Jesse M. Shapiro.
Augmented with some contributions borrowed from Arthur Turrell