Bread truck programming

As a programmer, you must always be writing your code for strangers to read, understand, and update. A clever solution that no other person can understand or modify is essentially dead code. I have heard this expressed a few different ways over the years, but my manager during my banking days referred to it as, "The bread truck problem".

You decide to enjoy the fine weather outside today with a brisk walk. As you are out and about, soaking in a little bit of sun and maybe listening to your favorite podcast about the history of World War 2, you step out to cross the street and WHAM, the bread truck of doom runs you over...

We'll hope that you make a full recovery, eventually, but what happens to the code and work you have left behind? Can someone else pick up from where you left off? If they can't, you have not done your job correctly. You didn't create a knowledgebase (in whatever form that takes) for someone else to come along and figure out what you were doing, why you were doing it, and how to continue your work.

"But Richard, I don't care what happens after the bread truck of doom has struck me down in the prime of life!" Oh, you selfish and naive person. The stranger who you are creating documentation for. That unknown future worker is you. Projects grow in scale and complexity over time, I have never worked on a code base where the customer didn't always want just one more feature. Some of those features are awesome, so you build them. Go through that cycle enough times over a long enough period of time and you will start to forget things. In six months or a year, you will end up editing or modifying code and thinking to yourself, "Which jerk wrote this?! I don't know what's going on here at all!"

That's you. You were that jerk.

From a company owner's perspective, the Bread Truck (or bus or car or whatever is culturally appropriate for you) Problem is all about being able to have a stable and productive system that he/she can hire programmers to work on. They are (hopefully) paying you a fair salary to do this work and you need to provide a way for that to happen.

From a purely selfish perspective, you will forget what you did in this function 6 months from now if you are not interacting with it on a daily basis. Future You will not have any way of knowing who requested a change, or why. The only way Future You is not going to curse your name is to make their job easier.

• Clear coding guidelines (that you follow)
• A comprehensible system layout
• Passwords and keys (NOT your private ssh keys) in a secure location that someone in charge has access to
• Documentation where it is appropriate, enough that someone else (Future You) can come in an pick up where you left off
• A code repository where your commits give some indication about what you were doing and why (ideally, with links to the Jira case you were working)

Honestly, if you have any experience at all, you already know what you wish the programmer ahead of you had done to make your job easier. Just do that. Do it for your company, yes. But also, do it for Future You.