I guess we were talking at cross-purposes. I was thinking more of internal APIs, the kind used by one group of developers possibly in the same source as the application they're working on. There at least, the documentation tends to be worth far less than the code it attempts to document, not least due to braindead IDEs generating crap like the following:
/** * TODO To change this template go to File | Settings | Templates * * @param name * @param age * @return */ The actual useful gems of documentation get lost in generated or hand-written nonsense. For better-documented projects such as Spring or Guava, sure, I'm less likely to actually read the source but I am quite fond of opening it and then using IDEA's normal code navigation keys instead of googling for the API, finding the right version and then navigating the poor frameset that javadoc still spits out. On Aug 21, 2012 7:19 PM, "Jon Kiparsky" <[email protected]> wrote: > "toy" projects as in ones whose failure is bit going to cause me any > problems- stuff I'm doing for fun our to try a new idea or whatnot. Not a > complicated notion > > For a project that isn't a toy, I will generally look for libraries that > seem to be far enough along in development that I can expect a degree of > stability and correctness. After all, I'm trying to write a program, I > don't want ti get tired to in fixing someone else's library. Complete and > correct docume > ntation is a good signal to look for. Incomplete and incorrect > documentation suggests something that's not ready for prime time. > Again, this is how I approach the question. Your willy may vary. > > > On Tuesday, August 21 2012, Ricky Clarkson <[email protected]> > wrote: > > In real world projects as opposed to toy ones(*), you do get > > mismatching code and javadoc, and you can't assume that deleting and > > rewriting the code is the right approach as you're not privvy to all > > the decisions that went into it. Your best bet is to assume the code > > works and is correct until you find out the opposite, as chances are > > it does work and is correct unless it's in an unused part of the > > codebase or you're working on something that flat out doesn't work at > > all. > > > > (*) I'm not sure whether you're willy-waving there but it can > > certainly be read as such. /Your company must be tiny if you need to > > willy-wave on newsgroups/ :) > > > > On Tue, Aug 21, 2012 at 5:34 PM, Jon Kiparsky <[email protected]> > wrote: > >> I would generally assume that if the javadoc is incorrect, then the > code if > >> either too buggy or too unstable to use in anything but a toy project. > >> Just my way off looking at it, your mileage may vary. > >> > >> > >> On Tuesday, August 21, 2012, Ricky Clarkson <[email protected]> > >> wrote: > >>> I'd rather make a bold than a timid claim. > >>> > >>> I have better tools for navigating code than I do Javadoc, and if I'm > >>> reading code I see the Javadoc too; code is the superset of > >>> information. When I want to investigate an API I tend to just open > >>> the code in IDEA. I might not happen to read any of it, just use > >>> Ctrl-F12 and Ctrl-Q to see the information I need, but if I do need to > >>> drill down I'm already in the right place. > >>> > >>> On Tue, Aug 21, 2012 at 3:44 PM, Jeb Beich <[email protected]> wrote: > >>>>>>"And as a user of an api, would you rather read the code or the > javadoc > >>>>>> ? > >>>>>> " > >>>> > >>>>>The code, in general. It's more likely to be correct. If the code > looks > >>>>> bad then the javadoc *might* clarify the intent but commit messages > are > >>>>> more > >>>>> likely to be accurate assuming you don't have a 'Latest changes' guy > on > >>>>> the > >>>>> team. > >>>> > >>>> That seems like a pretty bold claim to make in general. javadoc can be > >>>> pretty useful for getting a bird's eye view of the big api, then > zooming > >>>> in > >>>> to what you need. That's nice for a variety of reasons, such as > comparing > >>>> two similar libraries. > >>>> > >>>> -- > >>>> You received this message because you are subscribed to the Google > Groups > >>>> "Java Posse" group. > >>>> To post to this group, send email to [email protected]. > >>>> To unsubscribe from this group, send email to > >>>> [email protected]. > >>>> For more options, visit this group at > >>>> http://groups.google.com/group/javaposse?hl=en. > >>> > >>> -- > >>> You received this message because you are subscribed to the Google > Groups > >>> "Java Posse" group. > >>> To post to this group, send email to [email protected]. > >>> To unsubscribe from this group, send email to > >>> [email protected]. > >>> For more options, visit this group at > >>> http://groups.google.com/group/javaposse?hl=en. > >>> > >>> > >> > >> -- > >> You received this message because you are subscribed to the Google > Groups > >> "Java Posse" group. > >> To post to this group, send email to [email protected]. > >> To unsubscribe from this group, send email to > >> [email protected]. > >> For more options, visit this group at > >> http://groups.google.com/group/javaposse?hl=en. > > > > -- > > You received this message because you are subscribed to the Google > Groups "Java Posse" group. > > To post to this group, send email to [email protected]. > > To unsubscribe from this group, send email to > [email protected]. > > For more options, visit this group at > > -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/javaposse?hl=en. > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.
