JavaDoc and Comments - Java Posse

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion JavaDoc and Comments
Received-SPF: pass (google.com: domain of ricky.clark...@gmail.com designates 74.125.82.173 as permitted sender) client-ip=74.125.82.173;
MIME-Version: 1.0
In-Reply-To: <CAJ8m59AQRasSV6EhrM8JrVdC6CsiRp0bhwpT-7Mw-pbkYyW...@mail.gmail.com>
References: <180e8d3c-487b-4a12-9562-e5e8d665dbce@googlegroups.com>
 <4653a828-414c-4418-8153-13d7ef477b5d@googlegroups.com> <CAOBi2H-xFNfj1Uvh7Gj3PAVR3VRss=FD0kLCMwH-vR0XB1F...@mail.gmail.com>
 <CANhxj0VHSYAbhjXfNUH1WAJbATOPnSrgZLoiuaSA_mPg8aY...@mail.gmail.com>
 <CAOBi2H-OaoMnL27=k6An6_YQZvAd0-9Rj-2cTL=hB=4vOv3...@mail.gmail.com> <CAJ8m59AQRasSV6EhrM8JrVdC6CsiRp0bhwpT-7Mw-pbkYyW...@mail.gmail.com>
From: Ricky Clarkson <ricky.clark...@gmail.com>
Date: Tue, 21 Aug 2012 18:13:23 -0300
Message-ID: <CAOBi2H-Jmra9grVY3x+3gwcXFV959jN-u5dUbmSFN3iTwfF...@mail.gmail.com>
Subject: Re: [The Java Posse] JavaDoc and Comments
To: javaposse@googlegroups.com
Content-Type: text/plain; charset=UTF-8

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 <jon.kipar...@gmail.com> 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 <ricky.clark...@gmail.com>
> 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 <jebbe...@gmail.com> 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 javaposse@googlegroups.com.
>>> To unsubscribe from this group, send email to
>>> javaposse+unsubscribe@googlegroups.com.
>>> 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 javaposse@googlegroups.com.
>> To unsubscribe from this group, send email to
>> javaposse+unsubscribe@googlegroups.com.
>> 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 javaposse@googlegroups.com.
> To unsubscribe from this group, send email to
> javaposse+unsubscribe@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/javaposse?hl=en.
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
