I like Mortgage-Driven Development. Matthew Farwell.
2012/8/22 Kevin Wright <[email protected]> > 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. > -- 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.
