Though it pains me... I have to agree with you Cedric ;-) Another bug-a-boo is intent.. the intent of the author sometimes doesn't come through in the low level view you get from the code. I'd guess another example.. imagine using the regular expression package without both intent and lower level information being included in the javadoc.... it would be reachable to most even if the code were 100% readable... which is rarely ever is.
-- Kirk On 2013-04-14, at 8:15 PM, Cédric Beust ♔ <ced...@beust.com> wrote: > 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 <reini...@gmail.com> > 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 javaposse+unsubscr...@googlegroups.com. > To post to this group, send email to javaposse@googlegroups.com. > 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 javaposse+unsubscr...@googlegroups.com. > To post to this group, send email to javaposse@googlegroups.com. > 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 javaposse+unsubscr...@googlegroups.com. To post to this group, send email to javaposse@googlegroups.com. Visit this group at http://groups.google.com/group/javaposse?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
