4 ms·

I’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

I’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).

throw1234651234 6y ago
Give me an example, and I will write you code documenting the business context.
- Jtsummers 6y ago
  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.
mjw1007 6y ago
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.
- gimboland 6y ago
  Yes. Floyd-Hoare logic is worth learning about in this sense — a formal system for imperative languages where the rules essentially say "given preconditions X and code Y, if X is true before you run Y, we guarantee Z to be true afterwards". I've never ever ever proven code correct using this formalism, but that way of thinking permeates my every action as a programmer.
lmilcin 6y ago
Whether or not to document "how" will depend on the target audience. The code is written for people to read and only incidentally for computers to execute. From that point of view the target audience will matter a lot. I agree that in most cases, you expect the audience to be on level with the code and if you are writing code that is not on level with the audience (for example it is way too advanced) then you are doing something wrong (at the very least not considering who will be working with it). But not always. Example: I do with a lot of bright quants. With regards to code that does a lot of complicated calculations, they typically understand "why" but might need help with understanding "how". Another example: when your audience is mostly junior team you might want to explain "how". My current project starts using more and more reactive constructs and oftentimes I throw in an explanation of "how" when I, for example, get queries to explain during code reviews.

throw1234651234 6y ago

Give me an example, and I will write you code documenting the business context.

Jtsummers 6y ago
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.

mjw1007 6y ago

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.

gimboland 6y ago
Yes. Floyd-Hoare logic is worth learning about in this sense — a formal system for imperative languages where the rules essentially say "given preconditions X and code Y, if X is true before you run Y, we guarantee Z to be true afterwards". I've never ever ever proven code correct using this formalism, but that way of thinking permeates my every action as a programmer.

lmilcin 6y ago

Whether or not to document "how" will depend on the target audience. The code is written for people to read and only incidentally for computers to execute. From that point of view the target audience will matter a lot. I agree that in most cases, you expect the audience to be on level with the code and if you are writing code that is not on level with the audience (for example it is way too advanced) then you are doing something wrong (at the very least not considering who will be working with it). But not always. Example: I do with a lot of bright quants. With regards to code that does a lot of complicated calculations, they typically understand "why" but might need help with understanding "how". Another example: when your audience is mostly junior team you might want to explain "how". My current project starts using more and more reactive constructs and oftentimes I throw in an explanation of "how" when I, for example, get queries to explain during code reviews.