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!
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;
}
Given the prevelance of mutating functions in Java this is welcome
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.