I frequently harp about how important it is that maintainers of your code need to get context quickly to be productive and happy. I just thought of an analogy. Remember in the Jason Bourne movies, Jason gets in a car, glances at a map and becomes an expert in navigating old-world city streets? That’s the same expectation 100% of codebases have. Plucky protagonists can navigate with ease. But could your parents do this? How long would it take for someone new to navigate your codebase?
Follow conventions. Is everyone driving on the right hand side? You should too. Don’t invent new things. Most problems have known and familiar solutions. Beware NIHS, not invented here syndrome. (obligatory xkcd/927). You’ll have to bite the bullet and not have some customization; make sure all the customization you’re doing adds real value.
Have fewer rules. How many things do you have to keep track of? Are there weird rules to follow? These days, rules can be automatically enforced for you. Small functional style code has fewer rules to keep track of.
Make it easy to navigate. Do the streets make sense? Chicago’s grid streets were a boon to navigating the city. I hear Phoenix has expanded on that idea and is very easy to navigate. Does your city have multiple names for the same street? Do names repeat? Do you have to jump through twelve layers of abstraction to see what anything is doing? I wish I was exaggerating, but that’s the norm here.
Have fewer streets. If the only road is Main St, you just need to figure out if you’re supposed to go left or right. We often make up for difficult context by writing more documentation. What you’re really doing is adding more streets to navigate. If you don’t have to optimize for performance, optimize for maintainability.
Remember how I said 100% of codebases have these problems? Doing these won’t fix things, but they’ll make them better. The extra complexity is your added value. Make sure it’s value you’re adding.
Additional Reading
- https://lepiter.io/feenk/developers-spend-most-of-their-time-figuri-9q25taswlbzjc5rsufndeu0py/ https://news.ycombinator.com/item?id=30858311
BONUS: I didn’t know they made five Bourne movies. I guess, like code, we extract all we can out of a well performing movie until it becomes overloaded. Then we reboot it.