Consider the Next Person
As developers, we can inherit the work of others. This could happen for many reasons. Perhaps the original developer(s) had moved on to another position within (or without) the company. Or maybe the initial iteration of the project was developed by a contractor. For whatever reason, projects and installations can get handed off to others.
In these projects, there may be little — or no — documentation. Hopefully the code is at least self-documenting. Hopefully.
But if not – then what?
When inheriting an undocumented mess, developing new features takes a temporary back seat. Depending on the importance and complexity of the installation, we may need to spend time assessing the build in-depth. We pilot through the unknown, gaining familiarity with the codebase and dependencies. We sift through lines of disheveled syntax hoping to uncover the secrets that kept this thing from crashing since it was originally built with PHP 5.x and jQuery 1.x, with a heavy focus on ensuring IE8 support.
We carefully plot our next move toward implementing “New Feature B” without breaking anything.
This struggle could easily be avoided for the next person, if the current person responsible takes documentation seriously.
If you are the current person, and the previously responsible party left you an undocumented network of mysterious internal API calls, fear not – pick your head up, figure it out, and leave it better than you found it.
It’s important to plan. Of course, it’s impossible to plan for everything. However, an attempt should be made to cover all the bases — at least, all the current bases. Working within an ever-evolving company has taught me that nothing is carved in stone: no procedure, workflow, or automation is ever permanent.
For this reason, documentation is important. Whether it’s self-documenting code, verbose comment blocks, or even just a clear explanatory git history, it’s necessary to leave the next-in-line some clues so they can pick up where we left off. If time allows us to describe the ins and outs of a complex function, let’s do it. However if time doesn’t allow for that level of gluttonous documentation, let’s write clear, digestible code which purpose can be deciphered by a novice programmer.
Code like Somebody’s Watching
I’ve found that I write my best code when I write it like somebody’s watching; like somebody’s reviewing every character, line, and indent.
Let’s code like the next-in-line developer is watching and learning from us, and we don’t want to hand down any bad habits. If that means second-guessing our work and searching online for the latest best-practices, let’s take five minutes and ensure we’re programming progressively.*
*Interesting caveat: Some time from now, we’ll look back on whatever project we’re working on today – and find numerous ways to improve it. We may want to rewrite it altogether.
To conclude, I present a rule which I practice and rely on, and that I hope may help others reading today: leave it better than you found it.