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