Recently I’ve been thinking about a particular practice that I’ve found extremely beneficial throughout my career – not only to me, but also to the developers and engineers I work with. In fact, when done properly, it can greatly improve entire projects.
It stems from a ubiquitous issue that seems to affect just about every software engineering team in one way or another. I’m talking about knowledge-capture. Specifically, capturing project knowledge or ‘code knowledge’ in the moment that it’s most fresh in your mind. In a week, a month or a year from now, you’ll have forgotten that critical piece of information, and it may have been the key that another engineer was looking for.
A recurring phenomenon
I’ve seen this in every job throughout my career. And I’m sure you’ve been there too. There’s a line of code written by someone who’s no longer on the project (or worse, has now left the company), and you have no idea what its purpose is. “What have they done here?” or “Why have they done it like this?”, you mutter to yourself in confusion.
Chances are, they had a very good and legitimate reason to take the route they did. But only they know why, and now they’re gone. Even if you could get hold of them, what are the chances that they’ll remember? “Ah yeah, that project. I’m sorry, I can barely remember what I had for breakfast.”
The thing is, we can’t blame them – as busy software engineers, our heads are filled with rapidly-evolving information, and at our busiest, we can be pushed and pulled in a myriad of directions. Knowledge-capture is often not at the top of our ‘to-do’ list.
It’s different to documentation
Documentation can be a wonderful thing – when we have the time to write it. Ultimately, a client is paying for us to deliver code, and as long as you’re doing that well, they’re happy. While working on a project, it can be rare to find the downtime to put together documentation, and the client may not even see it as necessary.
Thankfully, we’re not under that kind of pressure at Kyan very often. But I’ve worked at other organisations where you barely get a moment to open a comment tag, let alone put together a document, no matter how small.
The other issue with documentation is that it can be very ‘detached’ from the actual code. For example, many codebases have a ‘readme’ file, often containing very useful information. But because it’s located in a completely different part of the codebase from the code you’re actually working on, people may not bother to update it, or even read it (despite its name!) So it may sit there for month after month with no one looking at it or contributing to it.
Even though it may contain a vital piece of information you need to resolve an issue during your current development task, it may not occur to you (especially when working under a tight deadline) to browse through a long ‘readme’ file in the hope that it might help you. The same problem can also affect wikis and other kinds of ‘detached’ documentation.
The golden key: making code understandable
In the first chapter of The Art of Readable Code, the authors propose a principle they call 'The Fundamental Theorem of Readability':
Code should be written to minimise the time it would take for someone else to understand it.
Of course, the goal should always be to write self-documenting code, which needs no documentation or explanation, since its purpose is expressed clearly via its structure and the names of its functions and variables. This is often possible for 99.9% of the code we write. But what about the remaining 0.1% which has an obscure purpose that can’t be determined from the code itself?
In my experience, the best place to capture such knowledge is in a comment right next to the code, and it can be as simple as one line of text or a link to a bug report online. In this way, the necessary knowledge is captured right there. No one has to waste time looking, hunting or digging around on the off-chance that they might find some documentation with relevance.
As a developer, I find this immensely helpful, and I’ve now made it my daily mission to do it wherever it’s beneficial. The comments themselves are often very short (“This is a workaround for a bug in the SDK” or “This fixes a layout issue in older versions of Safari”), but without them, something straightforward becomes a complete mystery.
A new discipline
It’s amazing how rapidly information can disappear from our minds. Agencies are busy, clients can be demanding, and projects can sometimes move at, well, sprint-like speed. Before you know it, the thought you had is gone, and you’re either dealing with another ticket or you’ve peacefully slipped into an afternoon of psytrance-induced deep focus.
By training ourselves to capture essential knowledge while it’s still fresh in our thoughts, we are making things immeasurably easier for the next person, and ultimately improving the overall health of the project too. Good quality understandable code = good quality of life.
This powerful technique can massively benefit everyone from the most senior engineer to the most junior developer. And whilst you may be thinking ‘This practice may take some time to get used to’, just think of all the hours you’ve spent struggling to understand enigmatic code, when a few simple code-comments could have saved you a great deal of stress and frustration.
So whilst this isn’t necessarily an instinctive practice, it can significantly improve the maintainability of a codebase. I’ve seen my teammates do it, and it helps me enormously. In return, I do it to help my teammates.
I’ll say it again. Good quality understandable code = good quality of life for you and your colleagues.
We are Kyan, a technology agency powered by people.
