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