Code only says what it does
brooker.co.za
Code only says what it does
1–10 of 120 posts
Re: Code only says what it does
#2I’ve had similar arguments here once or twice. There’s so much context that isn’t deducible from code.
You rarely need to document the “how” (that much should be evident if the code is well-written) but you absolutely should document the “why” (or, often as important, the “why not”: what code could be here but isn’t).
Re: Code only says what it does
#3When I teach coding I tell the students to document their code well but don't document what the code is doing it. That should be evident from the code itself (if it's not, then consider a refactor). Rather, explain why the code is doing it.
Re: Code only says what it does
#4I’ve had similar arguments here once or twice. There’s so much context that isn’t deducible from code. You rarely need to document the “how” (that much should be evident if the code is well-written) but you absolutely should document the “why” (or, often as important, the “why not”: what code could be here but isn’t).
Give me an example, and I will write you code documenting the business context.
Re: Code only says what it does
#5I agree with most of the points made here, though I think some of the bias toward up-front exhaustive documentation is probably not a good fit for most of the projects I've been a part of. Prototyping often reveals necessary changes due to resources constraints, or to unconsidered corner cases. Documentation needs to be a living thing as much as the code, and I think that pushes you toward documenting within the code more than externally.
One of the more important points the author brings up is that authorial intent and the 'why's of comments are the most important. A corollary I'll bring up to that is that the 'what's should be encoded in tests. Tests can be great documentation, and they have the added benefit of informing developers when the goals of the software is being voided (when they fail).
What has worked for me is conceiving of documentation this way:
- Design Documents: Historical use only, not to be updated.
- Readme: intro to project; why it exists, overview of how it's meant to function, how to edit, etc. Tends to be updated when big things change.
- Code comments: why something exists, what considerations were made in that code's creation
- Test descriptions and comments: binding goals of previous development to future development
This approach has done a pretty good job of keeping documentation from getting too out-of-sync with code while enforcing basic business objectives, still tilting the balance toward development rather than documentation.
Re: Code only says what it does
#6The marketing corollary is that metrics only tell you what happened, they cannot tell why. Yet somehow, entire companies have been built on the promise that they can answer the "why" by looking at the metrics.
Re: Code only says what it does
#7A big issue with documenting what the code does is that the code and documentation can very quickly fall out of sync. As this posts says, it's much more useful to document the intent of the code, or why there's this mess of seemingly hacky code (see issues #80681, #82108, #66065).
Also be wary of unit tests that are overly tied to the specifics of an implementation. These can be worse than useless when it comes to changing code. I.e. asking "why are my tests failing?" and finding out it's only because I breathed near the code.
Re: Code only says what it does
#8I’ve had similar arguments here once or twice. There’s so much context that isn’t deducible from code. You rarely need to document the “how” (that much should be evident if the code is well-written) but you absolutely should document the “why” (or, often as important, the “why not”: what code could be here but isn’t).
Give me an example, and I will write you code documenting the business context.
And then what? You throw away the example specification so that the why only continues on in the code?
And after 10 years of maintenance, the code has drifted with each iteration so that the why is no longer clear in the code.
Re: Code only says what it does
#9I’ve had similar arguments here once or twice. There’s so much context that isn’t deducible from code. You rarely need to document the “how” (that much should be evident if the code is well-written) but you absolutely should document the “why” (or, often as important, the “why not”: what code could be here but isn’t).
I agree that you shouldn't document "how", but when I'm reading unfamiliar code, I find I what I miss is "what", not "why".
To my mind, in well-written code each function should be documenting its contract: what it assumes, what it guarantees if that assumption holds.
(And if it turns out that what you'd write is just the function's name and its parameter and return types with a few grammatical particles added, maybe it's OK to omit the documentation.)
Then if you find that in order to do that you have to write a little essay, or you need terminology that doesn't correspond to a named thing in the codebase, or you're repeating yourself in multiple comments, that tells you something you need to put in higher-level documentation.
Re: Code only says what it does
#10Relevant: Writing system software: code comments. from http://antirez.com/news/124 + https://news.ycombinator.com/item?id=18157047