71–76 of 76 posts
I agree with useless comments but don't agree with blank 'constructor' method doc blocks that just say constructor as a filler.
Since most of the methods will have params/returns and better description than a simple constructor, leaving constructor without any doc-block is kind of counter productive and silly.
Earlier quoted context omitted.
Maybe a better way to clarify it's not ideal is to make a TODO. So: // TODO: Find out a better way to do this do.this(true)
TODO statements should be conserved to actual pending tasks. Code in this pattern is often a compromise, and may be found as contributory to future issues, but it probably didn't merit a follow-up task at the time of writing.
The example that he gives that I take issue with is the "Constructor" one in a JavaDoc comment. When using documentation tools, every undocumented function spews a warning. And that is as it should be. But some simple constructors don't have any functionality worth documenting. I code as if all warnings should be addressed, and that's true of my documentation generation. If a public function has no documentation, tha…
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, n…
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.
I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e. // do blah blah obvious_thing; obvious_thing; obvious_thing; obvious_thing; // do something else obvious_thing; obvious_thing; obvious_thing; obvious_thing; Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later. This is really useful in so…
Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..
Earlier quoted context omitted.
Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..
And now you have three places to look at instead of one.