|
|
|
|
|
|
by snarf21
2564 days ago
|
|
|
Not that documentation is bad but it is rarely correct. Now you have to spend time trying to match documentation that doesn't match the code you see. I always prefer a different approach. There is no need to document what a function does, that is self evident from stepping through it. The thing that should be included in the code is the WHY, meaning why does this function even need to exist and how does it fit into the architecture? Now an accurate high level architecture diagram and function raison d'etre telling you everything you need to know with much less risk of not having an accurate and up-to-date documentation process. |
|
|
It depends on what you mean by documentation. If you mean articles on Confluence or whatever, yeah, that's hopeless. If you mean comments in the code, I couldn't disagree more.
I don't buy the common argument that comments easily become inconsistent with the code. I can't imagine changing a line of code and completely ignoring the comment above it, and I'd definitely require a fix if I saw someone else do that in a code review. That's just a ridiculous level of sloppiness.
> There is no need to document what a function does, that is self evident from stepping through it.
I'm afraid I disagree here too, though again conditionally depending on what you mean. Straightforward logic shouldn't be littered with superfluous comments. But on the other extreme, the fast invsqrt algorithm needs more of a comment than the canonical "what the fuck?"
Yes, given weeks of head scratching any arbitrarily-dense block of code will release its secrets, but that's not good engineering. Anyone can build a bridge by dumping a hundred billion dollars of concrete into the bay until it's dry; good engineering is doing it cost-effectively. A well-placed comment in some non-obvious logic can save time for a developer (likely you) every time they interact with it.