| > 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. 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. |