0

Often boolean setters are pretty self-explanatory, like setLogErrors($bool). I do see some benefit of providing some additional information in the documentation, in this instance maybe where these errors are logged. But how much documentation is too much, especially when it comes to documenting the value that is passed to the setter? Documentation tools like phpDocumentor would like that variable to be documented as well, but from the context it is pretty clear that it takes a boolean. Often I personally find it better when the code speaks for itself, especially in situations like this.

What is the best practice in situations like this? Should the argument be documented or not, how about the setter, should it be documented? Wouldn't the code readability improve if there was less documentation in this circumstance? I am not part of a large developing team and I don't read a lot of code written by others. I was hoping to gain some insight into what standards are set in larger organizations and what is the easiest for people to read when the code is not their own.

I hope this questions is not too opinion based.

Improve this question
1
  • 1
    I've seen such "self explanatory setters" to often have weird effects. In your example, I've encountered such methods that would do the exact opposite of what you'd think (iow, the boolean logic was reversed from the obvious). Best document what true and false mean at the very least.
    – jwenting
    Feb 28, 2014 at 9:14

2 Answers 2

Reset to default
3

For the most part I agree with you, but then a different point-of-view occurred to me, which is when using an IDE.

If I'm editing Java code using Eclipse, it's really handy to be able to mouse-over a method and see the JavaDoc. If the method hasn't been documented, say because it's "obvious", I don't get any documentation. That makes me wonder - did the programmer just not bother? Could it be doing something else, even though it looks simple? Whereas by adding the "obvious" JavaDoc, I can quickly check that the method does, indeed, just do what I think (this relies on the JavaDoc being accurate, of course).

Besides that, leaving methods undocumented can be taken by lazy developers as an excuse not to document other, less obvious methods. There's something to be said for keeping up your standards.

Improve this answer
3

Languages differ in this respect, but I vastly prefer single attributes, which can be documented in one place. Something like:

"""Whether errors should be logged or pass silently, True by default"""
log_errors = True

If you must have a getter and setter, the two should use almost identical docstrings. Document what the variable does, not just that you are setting a variable named log_errors.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.