commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles <gil...@harfang.homelinux.org>
Subject [Math] Conventions (Was: commit screw-up)
Date Sun, 20 Oct 2013 17:44:17 GMT
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.


Regards,
Gilles


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


Mime
View raw message