[TrianguloY]

Serious questions: for those of you who say "just read the code", don't you find it useful when your IDE autocompletes what a function does? I do. And sometimes you can't even read the code!

Note: I'm not talking about things that you know just by looking at the method itself, but things that are obvious when reading the code of the method only.

    /** This will return the data */
    Data getData() {...}

This is useless, But

    /** This will return true iff it's not empty */
    boolean isValid() {return !empty();}

This is useful. This is what a good documentation should provide, and having documentation in the code itself (that you can later extract to an html page or other) is way better than having it on a separate platform that you need to remember to update.

Edit: remember that this is library that other people will use, it's not an internal tool that only your team knows about.

[mjr00]

There's often a reason that you want to encapsulate details of the behavior in a library. What if the definition of valid changes in the future and you need to adjust isValid() to also return false if the data matches some other criteria, like being out of bounds? You can say "just change the comment" but the comment is effectively part of your public-facing API and you've just introduced a breaking change.

[TrianguloY]

I see you agree with my point. By introducing a breaking change you need to update the facing api, so what better place to not forget to change the api that to place it exactly where the code is!

[ptx]

If that documented behavior is part of the API contract, then the entire isValid function seems useless and should probably be removed – if it's intended to check emptiness, just use isEmpty which already does that (or rename isValid to isNotEmpty).

[mjr00]

uh, no, I don't agree with your point. Your example is turning a bugfix into a breaking change by describing the implementation details of a method its documentation, which becomes inaccurate after changing the implementation.

Good developers solve this by not describing the implementation details of functions in comments. This is commonly known as encapsulation.[0] This is why most libraries do not have comments detailing the implementation like you suggest.

[0] https://en.wikipedia.org/wiki/Encapsulation_(computer_progra...