If I can draw your (collective) attention to page 15: http://www.waterfall2006.com/Refuctoring.pdf
On 22 August 2012 06:42, [email protected] <[email protected]>wrote: > Yes, my comments about javadoc were written with the public library in > mind, specifically something prepared for the use of others who do not have > access to the source code. > It still seems to me a kind gesture to give the consumers of your code a > bit of a leg up, in the form of well-made documentary comments, but > internal libraries are a very different situation from public ones. > > Sent from my mobile. > (Typos courtesy of swype) > > > ----- Reply message ----- > From: "Ricky Clarkson" <[email protected]> > Date: Tue, Aug 21, 2012 3:54 pm > Subject: [The Java Posse] JavaDoc and Comments > To: <[email protected]> > > 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.
