commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Neidhart <thomas.neidh...@gmail.com>
Subject Re: [Math] Conventions
Date Sun, 20 Oct 2013 21:42:33 GMT
On 10/20/2013 11:34 PM, Gilles wrote:
> On Sun, 20 Oct 2013 22:15:18 +0200, Thomas Neidhart wrote:
>> On 10/20/2013 09:56 PM, Gilles wrote:
>>> On Sun, 20 Oct 2013 12:09:44 -0700, Phil Steitz wrote:
>>>> On 10/20/13 10:44 AM, Gilles wrote:
>>>>> Hi.
>>>>>
>>>>>>>
>>>>>>>> [...]
>>>>>>>
>>>>>>> I notice that you changed back the uppercasing of the "@param"
>>>>>>> Javadoc. I've a personal preference for having an uppercase letter
>>>>>>> there, but I'd like that we fix the _project's_ preference. I
>>>>>>> think that is important to have rules (yes, even trivial ones)
>>>>>>> so that people (both committers and new contributors) can
>>>>>>> unequivocally know what is expected in as many areas as possible.
>>>>>>> This will reduce the amount of work for everyone.
>>>>>>> [Sorry for the little hijacking of this thread.]
>>>>>>
>>>>>> Unfortunately, I do not agree with that convention.  It is not
>>>>>> standard and most of the code (including the rest of the class)
>>>>>> follows the standard convention (see the Oracle / Sun docs).
>>>>>>
>>>>>
>>>>> I'm fine with whatever we have to follow, but this should be fixed
>>>>> once and for all, to avoid any spurious change that happens to suit
>>>>> one's preferences.
>>>>> We can follow what is used in most of the JDK docs. Let's just say
>>>>> that it is what we do, and then let's do it: the class here does not
>>>>> do that; if it were, a comment like "number of successes" would
>>>>> rather be "the number of observed successes" (i.e. using the word
>>>>> "the" and with emphasis on repeating "observed" so that the comment
>>>>> is not just the parameter name with spaces).
>>>>>
>>>>> I know that this sounds trivial; the problem is that everybody can
>>>>> come up with good reasons for what he is used to do. When someone
>>>>> contributes to a project, there are things that must be done
>>>>> because... it is so. Fixing trivial rules has good consequences
>>>>> since even new contributors can easily follow those rules.
>>>>> It will short-circuit a certain amount of discussion and less work
>>>>> for reviewers/committers.
>>>>
>>>> I suggest, once again, that we follow the Oracle conventions [1].
>>>> The relevant bit for this nit is
>>>>
>>>> "Parameter names are lowercase by convention. The data type starts
>>>> with a lowercase letter to indicate an object rather than a class.
>>>> The description begins with a lowercase letter if it is a phrase
>>>> (contains no verb), or an uppercase letter if it is a sentence. End
>>>> the phrase with a period only if another phrase or sentence follows it.
>>>>
>>>> Example:
>>>>
>>>> * @param ch        the character to be tested
>>>> * @param observer  the image observer to be notified
>>>>
>>>> ...
>>>> When writing the comments themselves, in general, start with a
>>>> phrase and follow it with sentences if they are needed.
>>>>
>>>>   *
>>>>
>>>>     When writing a phrase, do not capitalize and do not end with a
>>>>     period:
>>>>
>>>>     @param x  the x-coordinate, measured in pixels
>>>>
>>>>   *
>>>>
>>>>     When writing a phrase followed by a sentence, do not capitalize
>>>>     the phrase, but end it with a period to distinguish it from the
>>>>     start of the next sentence:
>>>>
>>>>     @param x  the x-coordinate. Measured in pixels.
>>>>
>>>>   *
>>>>
>>>>     If you prefer starting with a sentence, capitalize it and end it
>>>>     with a period:
>>>>
>>>>       @param x  Specifies the x-coordinate, measured in pixels.
>>>>
>>>>   *
>>>>
>>>>     When writing multiple sentences, follow normal sentence rules:
>>>>
>>>>       @param x  Specifies the x-coordinate. Measured in pixels."
>>>>
>>>
>>> IMHO, this shows that there is really no standardization. E.g. what I
>>> proposed in a previous discussion on this subject is also quite close
>>> to an "Oracle rule", namely,
>>>  If you prefer starting with a sentence, capitalize it and end it
>>>  with a period.
>>> And particularly
>>>  When writing multiple sentences, follow normal sentence rules.
>>>
>>> Which I would in effect _simplify_ further as simply: Follow normal
>>> sentence rules.
>>>
>>>> I prefer to keep things as brief as possible.  That means @param is
>>>> generally a short phrase describing the parameter and rarely a full
>>>> sentence.  Adding "the" in front is OK but not necessary, IMO and I
>>>> would like to keep the content and formatting rules as simple and
>>>> non-restrictive as possible.  I disagree with the statement that
>>>> more rules means less work.  It is actually the opposite.  Fewer
>>>> hard rules means less work both for contributors and committers.  I
>>>> would much rather have us focus on the *meaning* and *comprehension*
>>>> of the javadoc than nits about formatting.
>>>
>>> This is exactly what I postulated: I can explain my preferences, you
>>> can explain yours, and we won't have a standardized source code.
>>> Less rules means less work for oneself, and more work for the others
>>> (the project's team).
>>
>> First you start the discussion like that:
>>
>>>>> I'm fine with whatever we have to follow, but this should be fixed
>>>>> once and for all, to avoid any spurious change that happens to suit
>>>>> one's preferences.
>>
>> there is a convention (Oracle javadoc guide, which I like a lot and try
>> to follow), and there are several people who prefer using it (especially
>> when working on multiple projects -> javadoc hell).
>>
>> But you don't like this one, refuse to accept it as a convention and
>> want to impose your own way of writing javadoc on others.
> 
> You quoted what I wrote; I mean what I wrote, and not your interpretation
> of it.
> 
> The so-called "Oracle guidelines" are not a convention. IMO, a _project_
> (not me!) can impose one choice among the many Oracle's suggestions.
> 
>> Based on such discussion, it will always be hard to impossible to reach
>> consensus, unless somebody gives way. And from my own experience, it
>> does not hurt to give way yourself from time to time ... ;-)
> 
> I'll give way; let's continue to writing the Javadoc in the way we "like".
> 
> I'm sorry I raised such an issue once more. At least, I realize that what
> you mean by "consensus" is a only a matter of finding people who agree on
> what they like.
> Do you like writing documentation? I don't; yet I know that it is useful...

Actually, I don't mind writing documentation, I think it is very
important. What I really like is *reading* javadoc, as it help so much
in understanding code if there is well written javadoc.

And imho, the oracle convention is very easy to read (in code) thats why
I prefer it over anything else.

Thomas

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message