Login | Register
My pages Projects Community openCollabNet

Discussions > dev > Re: Treatment of javadoc

Project highlights: Architectural Overview

joist
Discussion topic

Back to topic list

Re: Treatment of javadoc

Author jrobbins9
Full name Jason Robbins
Date 2000-07-06 10:12:56 PDT
Message I totally agree that comments should say something that is NOT clear
from the signature. If we want to identify these lines as something
that needs further work, I suggest we use "TODO: ad comment here".
That is a common commenting convention that allows use to use
'grep TODO *.java'.

jason!



>"Daniel L. Rall" wrote:
>>
>> David Pellegrini wrote:
>> >
>> > Hi Jason!
>> >
>> > jeffw has this nifty javadoc'er program called GhettoDoc. It's
>> > currently under his home directory on swallow, but I was thinking it
>> > would be useful to make it available to others. Should we add it to
>> > tigris.org as an OS utility? How would you like to treat it?
>>
>> As I mentioned earlier to Jeff, I see no value in the following:
>>
>> * @param connection A variable of type Connection
>>
>> This is redundant information, already supplied by JavaDoc. I want to
>> know *why* a variable is needed and *how* it's used, not *what* it is.
>> What I would rather see is an empty stub, waiting to be filled by the
>> next developer who touches the file or method:
>>
>> * @param connection
>>
>> This is no less information than is already provided by JavaDoc. If I
>> can't tell from the name and type the purpose of the variable, I already
>> have to go to the source code (to where the method is defined or used).
>> If I already have to go to the definition, it would be nice to have the
>> JavaDoc comment for the variable in question already stubbed out for me
>> and waiting to be filled with information gleaned from the source code.
>
>That's the idea. "A variable of type" serves as a search string so we can
>find these easily and fill them in. An alternative, I suppose, would be:
>
> * @param connection ADD_COMMENT_HERE
>
>... which would be more blatant and beg to be edited with something
>meaningful. ;^)
>
>-davidp

« Previous message in topic | 1 of 1 | Next message in topic »

Messages

Show all messages in topic

Re: Treatment of javadoc jrobbins9 Jason Robbins 2000-07-06 10:12:56 PDT
Messages per page: