Imagine this — you’re working tirelessly on a major new project. You’ve mapped out complex data flows, woven together algorithms, and swung for the fences with a delightful user experience design. Your code is undocumented, but you’re not worried. Code documentation is avoidable, you reason.
Days turn into weeks, weeks to months, and finally, you schedule a demo to end all demos.
It’s time to show off what you’ve built to colleagues, impress management, and have the team begin working on your glorious brainchild. Meeting invites are sent, you hop on the call and load up your trusty server. A barrage of technical questions hit you barely thirty seconds in.
How are you handling state management? What hooks did you use? How did you implement X, Y, and Z? Isn’t server-side rendering better here? What is the time complexity? Do you have any memory leaks? Why is the algorithm not working with concurrent executions?
Functions, methods, callbacks, webhooks, data mapping, error handling, API endpoints, database models, and on and on. You start to sweat.
You intuitively know how it comes together, you remember parts here and there. Unfortunately, going back in time to work out the details of a snippet you coded months ago is like trying to remember which cake you had on your 7th birthday. I’m told mine was a fruity vanilla sponge cake with chocolate frosting — but then again, who really knows…
Undocumented Code: The Phantom Menace
If you’re a developer who likes to get their hands dirty, and you’ve ever had to revisit code you worked on months — maybe even weeks ago — you probably felt the disorientation that occurs when you try to recall all the moving parts of the codebase and how they intertwine. You assumed you would remember it all afterwards because, well, you built it yourself. But our brains tend to free up space much like our laptops do when we load up too many browser tabs. RAM is limited, both in PCs and in humans.
You assumed you would remember it all afterwards because, well, you built it yourself.
Diving back into the maze of past projects, especially the particularly complex ones, can be a highly frustrating exercise. In our rush to deliver the next feature or fix a bug, we usually skew our focus heavily toward programming — the real exciting bits of work — while largely sidelining documentation. Developers might occasionally jot down some notes along the way, but commenting code rarely gets the attention it deserves.
As developers, we often fool ourselves into thinking that good code speaks for itself. We all know someone who has used this line of thinking to evade writing docs. I’ve done this more times I’d like to admit.
The multiple uses of a documented codebase
What may be a perfect version of a code snippet to you might just be a shabby soup of bits and bytes to someone else. Or even to your future self. With so many ways to achieve the same result in coding, it’s crucial to remember that a quick explanation can save you and your colleagues a ton of time in understanding, improving and building upon your work.
Many software engineers underestimate the downsides of undocumented code. Dev teams hit speed bumps when they work on projects where neither the implementations nor the intentions behind programs are clear. Without easy-to-follow comments, passing on tasks or getting new folks on board takes way longer. We risk forgetting important details, constantly pinging any developer who ever touched the code for clarifications, and teamwork just becomes that much messier.
What may be a perfect version of a code snippet to us might just be a shabby soup of bits and bytes to someone else. Or even to our future selves.
Without docs, we effectively code blindfolded — delaying time-to-market, accumulating technical debt, and ultimately setting our team up for mediocrity.
A New Hope
Now picture this scenario, but with a critical twist — a tool that effortlessly melds into your workflow. It studies each commit you make, grasps your intent, and quietly documents your software behind the scenes. Your very own code historian, if you will, fully immersed in your work.
The next time you’re asked a question, you’ll have fresh, reliable, refined docs at hand explaining your work. All without having lifted a finger. You hop back into a project you worked on years ago. A quick glance at the docs and you’re ready to pick up right from where you left off.
You’re happy, your colleagues are happy, and your cerebrum thanks you for it.
Wouldn’t that be nice?
Let’s strive to make our code accessible, understandable and valuable for years to come — both to us and to anyone else who engages with it. Check out Komment, a tool that automates software documentation without upsetting your development workflow.