Imagine a world where all the standard Javadoc (e.g. java.util.collections, java.util.concurrent, etc...) were stripped out...
I don't know about others, but not a week goes by without me reading and rereading all these Javadocs. I do this all the time. Sometimes for the same class over and over again, because this class is performing complex functionalities with a lot of edge cases (the concurrent classes are a good example of that). Occasionally, I dig into the source. Without Javadocs, these libraries would be a lot harder to use. Not because they are badly written or badly designed but because the source only explains *what* the code does, not *why* nor *how* it does it. The argument "Comments go bad over time and can't be enforced by the compiler" is a straw man, in my opinion: this is more about how you control the quality of the code that gets checked in that about comments themselves. Use proper code reviews and comments won't go bad. -- Cédric -- Cédric On Sun, Apr 14, 2013 at 11:44 AM, Reinier Zwitserloot <[email protected]>wrote: > On the discussion on whether comments are good or bad, I posit: > > Code which is eminently understandable based solely on the name of the > method, the code, and the names of variables and parameters is always > better than code which requires comments to be easily understood, and also > better than code which is just as understandable but which has comments in > it (those comments are therefore superfluous). The reason comments are, in > a vacuum, 'bad', is that they clutter up code and are impervious to unit > testing. In practice, they are also notorious for ending up out of date > because those familiar with the code are more likely to work on it, and are > also more likely to mentally screen out the comment and thus not realize > when it becomes out of date (and thus, misleading, very bad). > > Of course, let's be reasonable here: While in theory any and all comments > are code smells, they are pretty much always the lesser evil. Anything > beyond the most academic of projects is going to have some chunk of code > which does something in a somewhat weird way for a good but not immediately > obvious reason, and the right choice is definitely to add a comment to > explain what's happening. > > However, for a great many comments, it could have been solved with helper > methods. We should all aim to do that more. Helper methods make it easier > to test code and are more effective at helping people new to this code > understand it all than comments. > > The notion that comments are the lesser evil is even more true for APIs > (so, javadoc). The best theoretical API is fully understandable based only > on a quick tutorial video and the names of types, methods, and parameters. > In practice, there are caveats and other details that you shouldn't bother > putting into the tutorial or the names, but do warrant mention. Again, > lesser evil: It would be even better if the API was such a fantastic > mapping onto the problem domain that there aren't any caveats in the first > place, but in practice life just isn't that nice of course. > > > > I believe treating comments as 'bad, but not a big deal' leads to the > right decision in general. Comment where neccessary, put in reasonable (but > don't go entirely out of your way) effort to avoid writing them by cleaning > up code to alleviate the need for them, and at all costs don't comment just > for the sake of adding comments. > > -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at http://groups.google.com/group/javaposse?hl=en. > For more options, visit https://groups.google.com/groups/opt_out. > > > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/javaposse?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
