4 ms·

Documentation is not a substitute for reading the code, but rather a complement to it. Code by itself is a limited medium that can only do so much. Asking some

Documentation is not a substitute for reading the code, but rather a complement to it. Code by itself is a limited medium that can only do so much. Asking someone to rely solely on code to explain a complicated subject is counterproductive (the more complicated the code is, the harder it is to guess whether something in the code is a mistake, or working as intended with some unknown reasoning behind it). Documentation points out the non-obvious parts, the reasoning behind it, the subtleties, the gotchas (things to watch out for), the best practices, etc. Documentation is a map to guide the user, not an end-all-be-all about what the code does. When the code does non-obvious things or has non-obvious reasons, you need both code and documentation.

fxtentacle 4y ago
I would agree in general, but the comment I was replying to is criticizing the following documentation as arrogant: "If you aren’t willing to read the source of the function to learn what it does, we don’t want you anywhere near it." And I believe that might be reasonable for a complex function that cannot be exhaustively documented in any form shorter than the source code.
- kstenerud 4y ago
  I disagree, but I think this comes down to the wording and tone. The following would be perfectly justifiable and I'd agree with it wholeheartedly: "This code is incredibly complicated and we don't have the resources to document it properly. So please DO NOT GO ANYWHERE NEAR THIS CODE unless you've spent weeks/months studying it in depth. And even then, think twice!" One is a friendly "here there be dragons" style warning that explains some things (such as why it's not documented). The other is a passive-aggressive accusation followed by an "I know better than you, kiddo" style enforcement, which exudes arrogant presumption.
  - derefr 4y ago
    But that phrasing makes an entirely different point. It's not "we don't have the resources to document it properly" — it's more like... "There is no possible documentation that could help you to not screw up when using this function. We've tried. There used to be docs here — first as doc comments, then hidden within the function (to force you to read the function to find them), then as a special pre-commit lint rule that triggers when people add a new use of the function to the codebase without adding a special annotation to acknowledge it. None of it helped; people still screwed up the usage. Even the people who wrote the function screwed up in new usages of it — every time they tried! — because the number of things you need to remember to get right to use it, exceeds the capacity of any single human being's short-term working memory. The very existence of this function is Ozymandian arrogance. It should be banished from the Earth. The only problem is that people keep reinventing it. We're waiting for a sufficiently-smart linter, so we can teach it to not let people reintroduce any function isomorphic to this to the codebase; then we can truly excise it for good. In the meantime, we leave it undocumented, for a bit of security through obscurity: a thing that you can't find a good way of coming to a seeming understanding of, you're less tempted to use."

fxtentacle 4y ago

I would agree in general, but the comment I was replying to is criticizing the following documentation as arrogant: "If you aren’t willing to read the source of the function to learn what it does, we don’t want you anywhere near it." And I believe that might be reasonable for a complex function that cannot be exhaustively documented in any form shorter than the source code.

kstenerud 4y ago
I disagree, but I think this comes down to the wording and tone. The following would be perfectly justifiable and I'd agree with it wholeheartedly: "This code is incredibly complicated and we don't have the resources to document it properly. So please DO NOT GO ANYWHERE NEAR THIS CODE unless you've spent weeks/months studying it in depth. And even then, think twice!" One is a friendly "here there be dragons" style warning that explains some things (such as why it's not documented). The other is a passive-aggressive accusation followed by an "I know better than you, kiddo" style enforcement, which exudes arrogant presumption.
- derefr 4y ago
  But that phrasing makes an entirely different point. It's not "we don't have the resources to document it properly" — it's more like... "There is no possible documentation that could help you to not screw up when using this function. We've tried. There used to be docs here — first as doc comments, then hidden within the function (to force you to read the function to find them), then as a special pre-commit lint rule that triggers when people add a new use of the function to the codebase without adding a special annotation to acknowledge it. None of it helped; people still screwed up the usage. Even the people who wrote the function screwed up in new usages of it — every time they tried! — because the number of things you need to remember to get right to use it, exceeds the capacity of any single human being's short-term working memory. The very existence of this function is Ozymandian arrogance. It should be banished from the Earth. The only problem is that people keep reinventing it. We're waiting for a sufficiently-smart linter, so we can teach it to not let people reintroduce any function isomorphic to this to the codebase; then we can truly excise it for good. In the meantime, we leave it undocumented, for a bit of security through obscurity: a thing that you can't find a good way of coming to a seeming understanding of, you're less tempted to use."