|
|
|
|
|
|
by mjmahone17
4467 days ago
|
|
|
If you're only documenting after the fact, your function isn't worth documenting: it means you conceptually understood it well enough that you didn't have to think much about it's inputs or outputs. If you did have to think through it, or your code reviewer doesn't understand it, add a comment explaining it. In any other case, commenting on it is probably useless and adding to clutter. Javadocs are painful to read, not because it's a bad idea, but because so often it's things like "toString(): returns a string that is the string of this object".
Sorry, I only need to know that function exists and it's return. I want to be able to scan through and see only those functions that are conceptually strange or unique, not the boilerplate that every class has to have, and is identical. If there's a comment on the toString() function, it had better be documenting something interesting, or else it's more useless than nothing. |
|
|
I can't disagree more. You can completely understand what you intend as you're writing a function, and then later, as you look back with a fresh perspective, realize in what way(s) the function could be misunderstood.
>Javadocs are painful to read, not because it's a bad idea, but because so often it's things like "toString(): returns a string that is the string of this object".
Straw man. "Bad docs are painful to read." Sure they are. If you have good documentation practices, you'll explain in toString() HOW the object is represented. "Return A string that indicates the (derived) object type, its x,y coordinates, and its current state, along with any additional state specific to the derived object type. You should not rely on its precise format, as it may change in the future."
The real problem is that most documentation sucks. But the only way that developers will ever get better at documentation is to practice.
I also am confused as to why "scanning" JavaDocs would ever need to be a thing; you do end up with your JavaDocs as a web page or help file, right?
If I'm confused about a function, I want to be able to click on it and see docs; if there are no docs on half the functions, that's a failure of the imagination of the API author(s). If they can't see how someone might be confused, and yet I'm confused, then they blew it.