"I don't need to write comments. The code is the documentation."
I once had a Senior Engineer use this argument to push back against documentation requirements. She was a brilliant coder, and her logic was technically sound—her variable names were clear, her functions were small, and her syntax was elegant.
She left the company within a year. The remaining team spent the next year trying to decipher, debug, and refactor the systems she left behind. Why? Because while her code was readable, her intent was invisible.
The Myth of Self-Documenting Code
Code is a set of instructions for a machine. It is excellent at communicating HOW a process is executed. It defines the syntax, the control flow, and the data structures.
But code is completely silent on the WHY.
When a new engineer opens a file written three years ago, the code shows them the destination. It does not show them the journey.
-
It doesn't explain that we chose this specific, slightly slower algorithm because the faster one caused a memory leak on mobile devices.
-
It doesn't explain that we hard-coded this value because the external API we rely on has a bug that the vendor won't fix.
-
It doesn't explain that this architecture was chosen to optimize for write-speed over read-speed due to a specific business requirement at the time.
Renting vs. Owning Your Codebase
Without this context—without the "Why"—you are not owning your codebase; you are renting it from the individuals who currently work there.
Your institutional knowledge is stored in RAM (people's heads), not on disk (documentation). When those key engineers leave, the context leaves with them. The code remains, but it becomes a "legacy black box"—something the new team is afraid to touch or refactor because they don't understand the constraints that shaped it.
Documentation as a Technical Skill
We need to reframe writing. It is not an administrative chore to be done after the "real work" is finished. It is a core technical skill.
Effective documentation doesn't mean writing 100-page requirement documents that no one reads. It means capturing the decisions:
-
Architecture Decision Records (ADRs): A lightweight text file that records a decision, the context, and the consequences. (e.g., "We are using Postgres instead of Mongo because we require ACID compliance for financial transactions.")
-
The "Why" Comment: Don't write comments that explain what the code is doing (
// increment i by 1). Write comments that explain why it's doing it (// We must increment here to bypass the header row in the CSV). -
The README: The high-level map that explains the business purpose of the service and how to run it locally.
Writing is a forcing function for thinking. If you cannot clearly write down why you are making a technical decision, you probably haven't thought it through deeply enough.