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: [email protected] > For additional commands, e-mail: [email protected] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
