4 ms·
Documentation can be utterly useless, if taken to the extreme. Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets
by OtomotO 2y ago
Documentation can be utterly useless, if taken to the extreme.
Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X"
No shit, captain obvious! Never would have guessed that.
I like a combination of "literate programming" (in a light form at least), that leads to readable, self explanatory code that's still fast and well (not prematurely) optimized.
But reading docs about the most trivial things: Brrr!
- kmoser 2y agoI'll gladly deal with a few (or even many) useless "this sets X" comments if they come along with helpful comments for other non-trivial methods.
- medo-bear 2y ago> Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" Given the prevelance of mutating functions in Java this is welcome
- OtomotO 2y agoNo, it's not. Because it doesn't add anything. Just document if something is mutating and what it mutates. Or simply name your functions accordingly. Like of your setter is doing a HTTP call, maybe name it so that it's obvious.
- elric 2y ago> Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" This has never been common in any sensible environment. Only on projects with project leads who had zero clue about anything, and with silly catch-all rules such as "EVERY METHOD MUST BE DOCUMENTED!". This predictably leads to shitty documentation. /** * Sets foo to <code>foo</code> * @param foo new foo value */ public void setFoo(int foo) { this.foo = foo; } No one sensible does this. Some IDEs might auto generate this garbage. In which case that should be disabled.
- OtomotO 2y agoWholeheartedly agree, but there is a lot of non sensible software out there ;-)
- rcxdude 2y agoIt's probably the largest fraction of javadoc by volume I've seen.
- elric 2y agoI'm sorry to hear that you've been plagued by shitty codebases. Have you considered trying to improve them? Or maybe try looking for greener pastures.