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 http://groups.google.com/group/javaposse?hl=en.
