The reluctance of software engineers to write documentation is a well-worn industry cliché. Some of that resistance is understandable — it’s tedious, it doesn’t ship features, and there’s a persistent belief that good code should explain itself. (Reflections about Chapter 6 of #HandsOn #SoftwareEngineering with #Python, available at https://lnkd.in/gRwyckDy) Maybe I’m a statistical fluke. Maybe I’ve just been burned often enough. Whatever the reason, I’ve come to see documentation as a stewardship responsibility. Here’s the test I keep coming back to: If I were new to this codebase — or returning to it after a long absence — could I safely add a feature, fix a bug, or refactor it using what’s written in the code itself? If the answer isn’t an immediate, unconditional “yes,” then the documentation isn’t done yet. The alternative is paying that cost later through interruptions, tribal knowledge, or avoidable mistakes. Self-documenting code helps explain what the code does. It rarely explains why it does it. That “why” often matters most when something goes wrong, or when constraints aren’t obvious from the implementation alone. Good documentation also acts as insurance: against turnover, against time, and against memory. Sometimes it’s as simple as a well-populated IDE help popup. Sometimes it’s the difference between confidence and fear when touching unfamiliar code. When documentation works, nobody notices. When it fails, everybody pays. #DeveloperExperience #EngineeringLeadership #MaintainableCode
I think people confuse comments and documentation. Long form comments can feel like documentation when they may just be describing/justifying inline why certain code exists. These are more likely informative to the dev working with code. Documentation on the other hand should go beyond and describe how to use the code, in the case of an API, and the intended purpose of the code. In many languages the documentation written with the code is used to generate the documentation pages/websites that exist apart from the code.
I tend to put a lot of effort into documentation also, probably because I could sometimes be accused of writing stuff that's too "clever" -- so I am anticipating questions/criticism -- since I can't resist "clever." Further, an old boss of mine Steve McElhinny, CISA told our team to imagine a loved one having to take over our code some day (assuming they could, technically) -- what would I want their experience to be? That's the mindset I have approaching documentation -- less about the mechanics and the technical and more about the intended emotion/experience.
I think it is the foundation of architecture and design to write your documentation as literate cognitive/code structuring. And if you're working with AI technology it's an essential requirement since it's the weakest area AI has is patterns, practices and systemic design architecture.
Good code doesn’t explain itself if it’s wrong. Part of code-level documentation is to outline what is expected so people who rely on it have a contract, so we know if the bugs are in the caller or the callee.
There’s really no excuse for sparse documentation anymore. Claude writes it all in seconds and it takes an hour, AT MOST, to review for accuracy. Or better yet, write the documentation and Claude will write the code!!
Documentation should explain caveats, the why, and the why nots. It should never explain the code, just the intent. It's rarely read unless there's a problem and it is out of date almost as soon as it's written. The key to good code is NOT good comments. It's picking nouns and verbs that non-technical people are already using to describe the business or problem space. Vocabulary that is unique to the tech and solution space is often unnecessary complexity and always prone to decay. Code is either glue or gears. We need both, but most projects, especially older ones that have been subjected to several engineers, have way way way too much glue. My favorite key is the DEL key.