You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Sébastien Brisard <se...@m4x.org> on 2011/11/25 08:13:06 UTC
[math] javadoc implicit formatting rules
Hi,
here are a few questions about the implicit rules in use in CM for
formatting Javadoc comments, that I've wanted to post for a long time.
Since I'm now reviewing other people's patches, I think it's high time
to clear these questions up. If I'm not mistaken,
(1) every @param tag should start with a capital letter and end with a period
(2) every @return tag should end with a period
When I first submitted a patch (and it was corrected accordingly), I
was a little surprised, since it is in contradiction with conventions
[1] which I (and obviously, others) was used to
(3) Regarding @param tags: "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."
(4) Regarding @return tags: "Use the same capitalization and
punctuation as you used in @param."
I'm not saying these conventions are good/bad. However, they are
consistent with automatic tags (eg "Specified by", which do *not* end
with a period). Besides, I think rules (1) and (2) are not
consistently enforced throughout CM (to take but one example: I
constantly find myself reverting to my old habits...) and so I'm
reluctant to correct other people's work to try and comply with rules
I'm not absolutely sure everyone agrees about.
I think it would be nice if everyone who is particularly attached to
an unstated rule just states it. We could then gather all those rules
in the Developers resources section of the website (I can do that,
please just write up the list in this thread). This would allow us,
and others, to refer to this document in order to ensure homogeneity
throughout the whole library.
What do you think? Best regards,
Sébastien
[1] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by Sébastien Brisard <se...@m4x.org>.
>
> It seems really a detail to me (your mileage may vary), the content of
> the javadoc being far more important than its form.
>
> Luc
>
That's the kind of answer I wanted to read, but I just wanted to
check. So when committing someone else's work, I won't worry about
that point.
Thanks,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by Sébastien Brisard <se...@m4x.org>.
OK, now I feel ashamed for raising such a trivial issue ;).
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by Phil Steitz <ph...@gmail.com>.
On Nov 25, 2011, at 3:49 AM, Luc Maisonobe <Lu...@free.fr> wrote:
> Le 25/11/2011 08:13, Sébastien Brisard a écrit :
>> Hi,
>> here are a few questions about the implicit rules in use in CM for
>> formatting Javadoc comments, that I've wanted to post for a long time.
>> Since I'm now reviewing other people's patches, I think it's high time
>> to clear these questions up. If I'm not mistaken,
>> (1) every @param tag should start with a capital letter and end with a period
>> (2) every @return tag should end with a period
>> When I first submitted a patch (and it was corrected accordingly), I
>> was a little surprised, since it is in contradiction with conventions
>> [1] which I (and obviously, others) was used to
>> (3) Regarding @param tags: "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."
>> (4) Regarding @return tags: "Use the same capitalization and
>> punctuation as you used in @param."
>>
>> I'm not saying these conventions are good/bad. However, they are
>> consistent with automatic tags (eg "Specified by", which do *not* end
>> with a period). Besides, I think rules (1) and (2) are not
>> consistently enforced throughout CM (to take but one example: I
>> constantly find myself reverting to my old habits...) and so I'm
>> reluctant to correct other people's work to try and comply with rules
>> I'm not absolutely sure everyone agrees about.
>>
>> I think it would be nice if everyone who is particularly attached to
>> an unstated rule just states it. We could then gather all those rules
>
> As far as I am concerned, I use neither upper case nor period for @param
> and @return. I think Gilles does, so clearly there is no agreed upon
> convention.
>
> It seems really a detail to me (your mileage may vary), the content of
> the javadoc being far more important than its form.
>
+100
Not worth arguing about. Key is content. Following standard conventions is better, but I can live with the nonstandard stuff as long as the content is correct and complete.
Phil
> Luc
>
>> in the Developers resources section of the website (I can do that,
>> please just write up the list in this thread). This would allow us,
>> and others, to refer to this document in order to ensure homogeneity
>> throughout the whole library.
>>
>> What do you think? Best regards,
>> Sébastien
>>
>> [1] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag
>>
>>
>> ---------------------------------------------------------------------
>> 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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by Luc Maisonobe <Lu...@free.fr>.
Le 25/11/2011 08:13, Sébastien Brisard a écrit :
> Hi,
> here are a few questions about the implicit rules in use in CM for
> formatting Javadoc comments, that I've wanted to post for a long time.
> Since I'm now reviewing other people's patches, I think it's high time
> to clear these questions up. If I'm not mistaken,
> (1) every @param tag should start with a capital letter and end with a period
> (2) every @return tag should end with a period
> When I first submitted a patch (and it was corrected accordingly), I
> was a little surprised, since it is in contradiction with conventions
> [1] which I (and obviously, others) was used to
> (3) Regarding @param tags: "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."
> (4) Regarding @return tags: "Use the same capitalization and
> punctuation as you used in @param."
>
> I'm not saying these conventions are good/bad. However, they are
> consistent with automatic tags (eg "Specified by", which do *not* end
> with a period). Besides, I think rules (1) and (2) are not
> consistently enforced throughout CM (to take but one example: I
> constantly find myself reverting to my old habits...) and so I'm
> reluctant to correct other people's work to try and comply with rules
> I'm not absolutely sure everyone agrees about.
>
> I think it would be nice if everyone who is particularly attached to
> an unstated rule just states it. We could then gather all those rules
As far as I am concerned, I use neither upper case nor period for @param
and @return. I think Gilles does, so clearly there is no agreed upon
convention.
It seems really a detail to me (your mileage may vary), the content of
the javadoc being far more important than its form.
Luc
> in the Developers resources section of the website (I can do that,
> please just write up the list in this thread). This would allow us,
> and others, to refer to this document in order to ensure homogeneity
> throughout the whole library.
>
> What do you think? Best regards,
> Sébastien
>
> [1] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag
>
>
> ---------------------------------------------------------------------
> 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] javadoc implicit formatting rules
Posted by Phil Steitz <ph...@gmail.com>.
On Nov 25, 2011, at 5:16 AM, Sébastien Brisard <se...@m4x.org> wrote:
>>
>> One more point on this. "Consistency" as some sort of independent goal by itself has no place in open source software. We need to keep our eyes on the prize, which is making it easy for users to understand and use the software and for volunteers to get involved. To the extent that consistent API and doco design contributes to these goals, great. But arcane rules or excessively complicated APIs that make it harder for people to use the software and get involved are to be avoided.
>>
>> Phil
>>
>
> Right. I'm going to grab a shovel and start digging a hole to bury
> myself in right now. For my defence, I remember having been asked to
> conform to those rules I was enumerating in my first post a while ago.
Hey - don't worry about it. As you can see we have diverse views. And it's great to get the benefit of your perspective.
Phil
> Whether it was something which had wide consensus was actually my
> question. Sorry Luc and Phil for taking your time.
> Best regards,
> Sébastien
>
>
> ---------------------------------------------------------------------
> 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] javadoc implicit formatting rules
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Fri, Nov 25, 2011 at 12:16:31PM +0100, Sébastien Brisard wrote:
> >
> > One more point on this. "Consistency" as some sort of independent goal by itself has no place in open source software. We need to keep our eyes on the prize, which is making it easy for users to understand and use the software and for volunteers to get involved. To the extent that consistent API and doco design contributes to these goals, great. But arcane rules or excessively complicated APIs that make it harder for people to use the software and get involved are to be avoided.
> >
> > Phil
> >
>
> Right. I'm going to grab a shovel and start digging a hole to bury
> myself in right now. For my defence, I remember having been asked to
> conform to those rules I was enumerating in my first post a while ago.
> Whether it was something which had wide consensus was actually my
> question. Sorry Luc and Phil for taking your time.
Well, don't be sorry, as I consider that consistency is an integral part of
a good project.
My view is constantly being misinterpreted: The argument is not on the
contents, which must be complete and accurate, and we all agree on this
_obvious_ truth.
Contents formatting is the _next_ step towards a higher standard of quality.
The Javadoc is a great idea (that documentation could be a nice read). So,
in the same way that you wouldn't buy a badly formatted book (or that
publishers of scientific papers, for instance, enforce consistent
formatting), the quality of documentation of a purposedly public project
should be as high as possible.
Consistency is the opposite of being arcane: it means that the same rules
are applied everywhere. And this ultimately facilitates communication.
I do not care what rules are selected, but I care a lot about consistency.
Quality, on _all_ fronts, should be the common goal.
Why argue about this indeed? Documentation is written once but read many,
many times. Why not capitalize or type the final period (if that's the
rule[1])? The extra effort is minimal compared to the time one would
usually need in order to write good _contents_.
Gilles
[1] As one example, I myself prefer to not put an "s" in a verbal form
(e.g. I'd write "Compute the sum..." instead "Computes the sum...").
I don't do it in my code, but I now do it in everything I write/correct
in CM, because it was the preferred choice here.
As Sébastien, and I before, asked, please state your preferred choices
and please, let's all stick, once and for all, to what the majority
decides.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br>.
I'm new to Apache and am following the mailing lists to learn more about the rules, policies, tools and so on. And I find this kind of discussion very useful, at least for me :-) So thanks for raising this issue here in the mailing list. And thanks to the others for giving good answers here too.
Have a nice weekend,
Bruno P. Kinoshita
________________________________
De: Sébastien Brisard <se...@m4x.org>
Para: Commons Developers List <de...@commons.apache.org>
Enviadas: Sexta-feira, 25 de Novembro de 2011 9:16
Assunto: Re: [math] javadoc implicit formatting rules
>
> One more point on this. "Consistency" as some sort of independent goal by itself has no place in open source software. We need to keep our eyes on the prize, which is making it easy for users to understand and use the software and for volunteers to get involved. To the extent that consistent API and doco design contributes to these goals, great. But arcane rules or excessively complicated APIs that make it harder for people to use the software and get involved are to be avoided.
>
> Phil
>
Right. I'm going to grab a shovel and start digging a hole to bury
myself in right now. For my defence, I remember having been asked to
conform to those rules I was enumerating in my first post a while ago.
Whether it was something which had wide consensus was actually my
question. Sorry Luc and Phil for taking your time.
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by Sébastien Brisard <se...@m4x.org>.
>
> One more point on this. "Consistency" as some sort of independent goal by itself has no place in open source software. We need to keep our eyes on the prize, which is making it easy for users to understand and use the software and for volunteers to get involved. To the extent that consistent API and doco design contributes to these goals, great. But arcane rules or excessively complicated APIs that make it harder for people to use the software and get involved are to be avoided.
>
> Phil
>
Right. I'm going to grab a shovel and start digging a hole to bury
myself in right now. For my defence, I remember having been asked to
conform to those rules I was enumerating in my first post a while ago.
Whether it was something which had wide consensus was actually my
question. Sorry Luc and Phil for taking your time.
Best regards,
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] javadoc implicit formatting rules
Posted by Phil Steitz <ph...@gmail.com>.
One more point on this. "Consistency" as some sort of independent goal by itself has no place in open source software. We need to keep our eyes on the prize, which is making it easy for users to understand and use the software and for volunteers to get involved. To the extent that consistent API and doco design contributes to these goals, great. But arcane rules or excessively complicated APIs that make it harder for people to use the software and get involved are to be avoided.
Phil
On Nov 25, 2011, at 2:13 AM, Sébastien Brisard <se...@m4x.org> wrote:
> Hi,
> here are a few questions about the implicit rules in use in CM for
> formatting Javadoc comments, that I've wanted to post for a long time.
> Since I'm now reviewing other people's patches, I think it's high time
> to clear these questions up. If I'm not mistaken,
> (1) every @param tag should start with a capital letter and end with a period
> (2) every @return tag should end with a period
> When I first submitted a patch (and it was corrected accordingly), I
> was a little surprised, since it is in contradiction with conventions
> [1] which I (and obviously, others) was used to
> (3) Regarding @param tags: "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."
> (4) Regarding @return tags: "Use the same capitalization and
> punctuation as you used in @param."
>
> I'm not saying these conventions are good/bad. However, they are
> consistent with automatic tags (eg "Specified by", which do *not* end
> with a period). Besides, I think rules (1) and (2) are not
> consistently enforced throughout CM (to take but one example: I
> constantly find myself reverting to my old habits...) and so I'm
> reluctant to correct other people's work to try and comply with rules
> I'm not absolutely sure everyone agrees about.
>
> I think it would be nice if everyone who is particularly attached to
> an unstated rule just states it. We could then gather all those rules
> in the Developers resources section of the website (I can do that,
> please just write up the list in this thread). This would allow us,
> and others, to refer to this document in order to ensure homogeneity
> throughout the whole library.
>
> What do you think? Best regards,
> Sébastien
>
> [1] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag
>
>
> ---------------------------------------------------------------------
> 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