You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles <gi...@harfang.homelinux.org> on 2013/10/20 21:56:44 UTC
Re: [Math] Conventions
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).
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Conventions
Posted by Phil Steitz <ph...@gmail.com>.
On 10/20/13 12: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.
I agree if what is needed / natural is a full English sentence. In
most cases that is neither natural nor necessary.
"The confidence level." is not a sentence. It has no verb. To
capitalize it and end with a period in incorrect, as the Oracle docs
suggest. If you really want to type the extra words "Specifies the
confidence level." so it can be a complete sentence, fine by me.
Just don't force me and other contributors to do it.
> 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).
Not if the project team agrees to less stringent rules. More rules
mean more constraints which means more work (both for reviewers and
contributors) and more barriers to entry for new contributors. I
would much rather see us focus on rules for what needs to be
included in the content of javadoc (full specification of
preconditions, descriptions and references for algorithms, what
happens when preconditions are not satisfied, etc.) than
micro-specifying formatting conventions (to me, anything beyond the
Oracle guidelines qualifies as micro-specifying).
Phil
>
>
> Regards,
> Gilles
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Conventions
Posted by Thomas Neidhart <th...@gmail.com>.
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
Re: [Math] Conventions
Posted by Gilles <gi...@harfang.homelinux.org>.
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...
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Conventions
Posted by Thomas Neidhart <th...@gmail.com>.
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.
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 ... ;-)
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org