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 Sadowski <gi...@harfang.homelinux.org> on 2011/01/11 16:15:49 UTC
[Math] Coding and documenting guidelines
Hi.
Is there a document presenting best practices for writing code for CM?
Right now I'm thinking about the recent overwrites of Javadoc comments; so I
think that it could be useful to lay out what should be there (beyond the
obvious that "everything should be documented").
A few things that come to mind:
* All exceptions that could be thrown must be documented in a "@throws" tag,
indicating all the possible causes of the exception (such as the
assumed preconditions)
* The "@param" tag should not contain redundant information (such as
preconditions since they must be documented in a "@throws" tag).
* Javadoc comments must be composed of full sentences (except for the
definition of a "@param"), including punctuation and uppercase at the
start of the sentence. E.g. write
/**
* @param x Value of the parameter. A value of -1 indicates that
* the parameter is not used.
*/
but not
/**
* @param x Value of the parameter. -1 for "not used".
*/
* The comment for a "@param" tag should not start with the word "the". E.g.
do not write:
/**
* @param x The value of the parameter.
*/
* In a "@param" description, do not repeat the name of the parameter. E.g.
do not write
/**
* @param x Value of the "x" parameter.
*/
* When a description starts with a verb, write it in the imperative form
(not the at the third person of the present tense). E.g. write
/**
* Compute the value of the function.
*/
rather than
/**
* Computes the value of the function.
*/
* The comment of a "@return" tag must be the sentence part that completes
the expression "This method returns ...". E.g.
/**
* @return the value of the function.
*/
or
/**
* @return a random value between 0 and 1.
*/
* Do not specify the type of the returned value. E.g. do not write:
/**
* @return a random double value between 0 and 1.
*/
* Avoid starting the description of a method with "This method".
* In Javadoc comments, expressions that include code statements must be
written inside {@code ...} constructs.
* Simple mathematical formulae must be included in {@code ...} or
<code>...</code> constructs.
* etc.
I think that complying with such rules will ensure completeness and clarity
without the overload of redundant information, and will go some way towards
uniformization of the documentation.
Best regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hello.
> On Tue, Jan 11, 2011 at 7:38 AM, sebb <se...@gmail.com> wrote:
>
> > On 11 January 2011 15:15, Gilles Sadowski <gi...@harfang.homelinux.org>
> > wrote:
> > > Hi.
> > >
> > > Is there a document presenting best practices for writing code for CM?
> >
> > Sun/Oracle have Javadoc conventions which should be followed.
> >
>
> See
> http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide
>
> <http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide>Note
> that several items there conflict with what Gilles suggested.
>
>
> > > * All exceptions that could be thrown must be documented in a "@throws"
> > tag,
> > > indicating all the possible causes of the exception (such as the
> > > assumed preconditions)
> >
> > +1
> >
>
> Certainly all checked exceptions. Unchecked exceptions are a bit more hazy.
> Should all code that has any arithmetic or pointer dereferencing document
> the related exceptions? Probably not.
We agreed that in CM we would aim at documenting _all_ exceptions (i.e.
null references too) caused by CM code.
> Clarity can be compromised by too
> much goo just as much as with too little.
>
I totally agree. (But see below also.)
>
> > > * The "@param" tag should not contain redundant information (such as
> > > preconditions since they must be documented in a "@throws" tag).
> >
> > -1
> >
> > It's a lot easier to read the preconditions in the param description,
> > rather than wading through all the throws descriptions to see if the
> > parameter is mentioned.
> >
> > But where there are only one or two params and throws the duplication
> > may be unnecessary.
> >
>
> Also -1 for exactly the reasons stated.
(1)
I agree that in the absolute, the best place for a parameter precondition is
in the "@param" tag description.
(2)
If the Javadoc format were perfect, we would be able to specify a
(hypothetical) "@precondition" together with an associated "@throws" if
violated. But we can't.
(3)
We must (CM policy, cf. above) have a "@throws" for each exception. And thus
we must also say when (i.e. describe the precondition) this particular
exception is thrown.
(4)
Hence the description of the precondition is redundant in the "@param" tag.
Another case is when a precondition is formed from a combination of several
parameters. Then it certainly makes more sense to describe it _once_ in the
"@throws" rather than several times, in each of the "@param" tags.
>From another standpoint, redundant information might be welcome if the
preconditions are not obvious. An additional explanation within the main
description could mention the "caveat"s.
However I'm against repeating the obvious in the "@param" tag. IMHO, the
example that triggered this discussion falls in this category: You have a
class named
BaseMultiStartMultivariateRealOptimizer
and you have a constructor parameter named
starts
Then the description
* @param starts Number of starts to perform.
* @throws NotStrictlyPositiveException if {@code starts < 1}.
is clear and complete (as far as the parameter "starts" is concerned).
While in this one:
* @param starts Number of starts to perform, must be >=1.
* Multi-start is disabled if {@code starts == 1}.
* @throws NotStrictlyPositiveException if {@code starts < 1}.
the same information is unnecessarily stated multiple times (obviously, the
number of starts must be positive, and, when "starts" is equal to 1, you
will have a single start).
Another example within CM is the repetition of something like "cannot be
null", at the "@param" or main description level, whereas I tend to think
that only the case "may be null" is unusual in CM (and thus worth
mentioning).
>
>
> >
> > > * Javadoc comments must be composed of full sentences (except for the
> > > definition of a "@param"), including punctuation and uppercase at the
> > > start of the sentence. E.g. write
> > > /**
> > > * @param x Value of the parameter. A value of -1 indicates that
> > > * the parameter is not used.
> > > */
> > > but not
> > > /**
> > > * @param x Value of the parameter. -1 for "not used".
> > > */
> >
> > I think the Javadoc standards may have useful guidance here too.
> >
>
> -1. Specifically the style standards suggest that sentence fragments
> *should* be used in some cases.
If you refer to
Okay to use phrases instead of complete sentences, in the interests of
brevity. This holds especially in the initial summary and in @param tag
descriptions.
I agree with that, as I said above "[...] full sentences (except for the
definition of a "@param"), [...]".
However I don't agree to sacrify clarity (in the sense of easy reading)
for the sake of saving a few typing strokes (cf. "Write once, read many
times").
>
> > > * When a description starts with a verb, write it in the imperative form
> > > (not the at the third person of the present tense). E.g. write
> > > /**
> > > * Compute the value of the function.
> > > */
> > > rather than
> > > /**
> > > * Computes the value of the function.
> > > */
> >
>
> Again, this is in direct contradiction with the style standards.
I know. But there is no best choice; it depends on how you interpret the
description (and how often you read the code vs the generated docs).
E.g. with the Java standard (3rd person indicative), you can read the
generated doc as e.g.
[The] "remove" [method] Removes the element [...]
Whereas I tend to prefer keeping the doc in sync with the actual "action"
(cf. "message passing"/imperative) of the method name:
/**
* Remove the element ...
*/
public E remove(int index) {
// ...
}
The generated doc would thus read
[Use the method] "remove" [in order to] Remove the element [...]
>
> > The class Javadoc needs to mention thread-safety (or otherwise).
> >
> > If user code needs to apply synch. to ensure thread-safety, then the
> > Javadoc should say what lock(s) need to be held.
> >
> > @since tags must be used where relevant
> > @deprecated/@Deprecated tags/annotations should say when the item was
> > deprecated, and when it is due to be removed (if known)
> >
> > @SuppressWarnings should be applied as close as possible to the code
> > that causes the warning (this may involve creating a temporary
> > variable) and should have a comment that explains why the warning is
> > safe to ignore.
> >
>
> These are all good if downgraded to a very strongly emphasized should
> instead of must.
Well this "Guidelines" document should in fact state what *must* be done.
If a developer does not know how to comply with all the rules, this list
should then help _before_ the commit. This will be less tedious than after
the fact clean-up (especially if the initial committer is not the one who
makes the clean-up...).
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Ted Dunning <te...@gmail.com>.
On Tue, Jan 11, 2011 at 7:38 AM, sebb <se...@gmail.com> wrote:
> On 11 January 2011 15:15, Gilles Sadowski <gi...@harfang.homelinux.org>
> wrote:
> > Hi.
> >
> > Is there a document presenting best practices for writing code for CM?
>
> Sun/Oracle have Javadoc conventions which should be followed.
>
See
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide
<http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide>Note
that several items there conflict with what Gilles suggested.
> > * All exceptions that could be thrown must be documented in a "@throws"
> tag,
> > indicating all the possible causes of the exception (such as the
> > assumed preconditions)
>
> +1
>
Certainly all checked exceptions. Unchecked exceptions are a bit more hazy.
Should all code that has any arithmetic or pointer dereferencing document
the related exceptions? Probably not. Clarity can be compromised by too
much goo just as much as with too little.
> > * The "@param" tag should not contain redundant information (such as
> > preconditions since they must be documented in a "@throws" tag).
>
> -1
>
> It's a lot easier to read the preconditions in the param description,
> rather than wading through all the throws descriptions to see if the
> parameter is mentioned.
>
> But where there are only one or two params and throws the duplication
> may be unnecessary.
>
Also -1 for exactly the reasons stated.
>
> > * Javadoc comments must be composed of full sentences (except for the
> > definition of a "@param"), including punctuation and uppercase at the
> > start of the sentence. E.g. write
> > /**
> > * @param x Value of the parameter. A value of -1 indicates that
> > * the parameter is not used.
> > */
> > but not
> > /**
> > * @param x Value of the parameter. -1 for "not used".
> > */
>
> I think the Javadoc standards may have useful guidance here too.
>
-1. Specifically the style standards suggest that sentence fragments
*should* be used in some cases.
> > * When a description starts with a verb, write it in the imperative form
> > (not the at the third person of the present tense). E.g. write
> > /**
> > * Compute the value of the function.
> > */
> > rather than
> > /**
> > * Computes the value of the function.
> > */
>
Again, this is in direct contradiction with the style standards.
> The class Javadoc needs to mention thread-safety (or otherwise).
>
> If user code needs to apply synch. to ensure thread-safety, then the
> Javadoc should say what lock(s) need to be held.
>
> @since tags must be used where relevant
> @deprecated/@Deprecated tags/annotations should say when the item was
> deprecated, and when it is due to be removed (if known)
>
> @SuppressWarnings should be applied as close as possible to the code
> that causes the warning (this may involve creating a temporary
> variable) and should have a comment that explains why the warning is
> safe to ignore.
>
These are all good if downgraded to a very strongly emphasized should
instead of must.
Re: [Math] Coding and documenting guidelines
Posted by sebb <se...@gmail.com>.
On 11 January 2011 15:15, Gilles Sadowski <gi...@harfang.homelinux.org> wrote:
> Hi.
>
> Is there a document presenting best practices for writing code for CM?
Sun/Oracle have Javadoc conventions which should be followed.
> Right now I'm thinking about the recent overwrites of Javadoc comments; so I
> think that it could be useful to lay out what should be there (beyond the
> obvious that "everything should be documented").
>
> A few things that come to mind:
>
> * All exceptions that could be thrown must be documented in a "@throws" tag,
> indicating all the possible causes of the exception (such as the
> assumed preconditions)
+1
> * The "@param" tag should not contain redundant information (such as
> preconditions since they must be documented in a "@throws" tag).
-1
It's a lot easier to read the preconditions in the param description,
rather than wading through all the throws descriptions to see if the
parameter is mentioned.
But where there are only one or two params and throws the duplication
may be unnecessary.
> * Javadoc comments must be composed of full sentences (except for the
> definition of a "@param"), including punctuation and uppercase at the
> start of the sentence. E.g. write
> /**
> * @param x Value of the parameter. A value of -1 indicates that
> * the parameter is not used.
> */
> but not
> /**
> * @param x Value of the parameter. -1 for "not used".
> */
I think the Javadoc standards may have useful guidance here too.
> * The comment for a "@param" tag should not start with the word "the". E.g.
> do not write:
> /**
> * @param x The value of the parameter.
> */
>
> * In a "@param" description, do not repeat the name of the parameter. E.g.
> do not write
> /**
> * @param x Value of the "x" parameter.
> */
>
> * When a description starts with a verb, write it in the imperative form
> (not the at the third person of the present tense). E.g. write
> /**
> * Compute the value of the function.
> */
> rather than
> /**
> * Computes the value of the function.
> */
>
> * The comment of a "@return" tag must be the sentence part that completes
> the expression "This method returns ...". E.g.
> /**
> * @return the value of the function.
> */
> or
> /**
> * @return a random value between 0 and 1.
> */
>
> * Do not specify the type of the returned value. E.g. do not write:
> /**
> * @return a random double value between 0 and 1.
> */
+0 - does not seem like a big deal.
> * Avoid starting the description of a method with "This method".
>
> * In Javadoc comments, expressions that include code statements must be
> written inside {@code ...} constructs.
>
> * Simple mathematical formulae must be included in {@code ...} or
+1
> <code>...</code> constructs.
AIUI <code> is obsolete.
> * etc.
The class Javadoc needs to mention thread-safety (or otherwise).
If user code needs to apply synch. to ensure thread-safety, then the
Javadoc should say what lock(s) need to be held.
@since tags must be used where relevant
@deprecated/@Deprecated tags/annotations should say when the item was
deprecated, and when it is due to be removed (if known)
@SuppressWarnings should be applied as close as possible to the code
that causes the warning (this may involve creating a temporary
variable) and should have a comment that explains why the warning is
safe to ignore.
>
> I think that complying with such rules will ensure completeness and clarity
> without the overload of redundant information, and will go some way towards
> uniformization of the documentation.
>
>
> Best 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] Coding and documenting guidelines
Posted by sebb <se...@gmail.com>.
On 13 January 2011 16:52, Jörg Schaible <jo...@scalaris.com> wrote:
> Hi Gilles,
>
> Gilles Sadowski wrote:
>
> [snip]
>
>>> Yes, though I don't see big problems with formatting and I don't see the
>>> need - and in fact see reasons not to - depart from the established
>>> standard or add more requirements that contributors need to follow.
>>
>> There are no big problems, just a lot of small ones (e.g. using a keywords
>> like "null" without writing it as "{@code null}" and some comments being
>> complete sentences while others aren't).
>> If this is not important (again, I'm not saying it should be
>> high-priority), then I'd strongly suggest to remove the "trailing white
>> space" rule from CheckStyle because that one should be orders of magnitude
>> less important...
>
> There's a reason for such a rule. Most modern editors will remove them
> automatically, but when the original file contained such stuff, you end up
> with a diff that contains a lot of clutter (not to mention the fact that
> this diff might be a patch from JIRA and someone else has to apply it and
> might get as a result stupid conflicts).
>
> Obviously formatting changes will produce always such clutter and therefore
> it is important to clean up the source at least before a release, because
> you can expect patches against the tagged version.
>
> Annoying as a unified code format is for the individual developer, it
> improves maintenance a lot.
+1
Also, trailing spaces can be trivially fixed automatically.
Changing null to {@code null} automatically is more of a challenge.
==
The most important objective for me is to ensure that the Javadoc is
complete and accurate.
Having a consistent style may help to make it more readable - or it
may not, if the style does not sit well with the reader.
I think it's far more important to ensure that committers are
encouraged provide the Javadoc, without having to worry about using
the correct "language".
> Just my 2¢
> Jörg
>
>
> ---------------------------------------------------------------------
> 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] Coding and documenting guidelines
Posted by Jörg Schaible <jo...@scalaris.com>.
Hi Gilles,
Gilles Sadowski wrote:
[snip]
>> Yes, though I don't see big problems with formatting and I don't see the
>> need - and in fact see reasons not to - depart from the established
>> standard or add more requirements that contributors need to follow.
>
> There are no big problems, just a lot of small ones (e.g. using a keywords
> like "null" without writing it as "{@code null}" and some comments being
> complete sentences while others aren't).
> If this is not important (again, I'm not saying it should be
> high-priority), then I'd strongly suggest to remove the "trailing white
> space" rule from CheckStyle because that one should be orders of magnitude
> less important...
There's a reason for such a rule. Most modern editors will remove them
automatically, but when the original file contained such stuff, you end up
with a diff that contains a lot of clutter (not to mention the fact that
this diff might be a patch from JIRA and someone else has to apply it and
might get as a result stupid conflicts).
Obviously formatting changes will produce always such clutter and therefore
it is important to clean up the source at least before a release, because
you can expect patches against the tagged version.
Annoying as a unified code format is for the individual developer, it
improves maintenance a lot.
Just my 2¢
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Thu, Jan 13, 2011 at 10:34:00AM -0500, Phil Steitz wrote:
>
>
>
>
> On Jan 13, 2011, at 7:21 AM, Gilles Sadowski <gi...@harfang.homelinux.org> wrote:
>
> > Hi.
> >
> >> [...]
> >>>
> >>>> A couple of areas where we have slipped a bit over the years that I
> >>>> would rather apply energy to than formatting are the following (from
> >>>> the Developers' guide):
> >>>>
> >>>> # All component contracts must be fully specified in the javadoc
> >>>> class, interface or method comments, including specification of
> >>>> acceptable ranges of values, exceptions or special return values.
> >>>> # External references or full statements of definitions for all
> >>>> mathematical terms used in component documentation must be provided.
> >>>> # Implementations should use standard algorithms and references or
> >>>> full descriptions of all algorithms should be provided.
> >>>> # Additions and enhancements should include updates to the User Guide.
> >>>
> >>> This is all OK, of course. But what I had in mind is more of a "cheat
> >>> sheet", that can be checked easily by the developer (and maybe partly by
> >>> CheckStyle?) so that we can be sure that the doc is both complete and a
> >>> pleasant read (which, I'm convinced, is helped by a consistent form).
> >>>
> >>
> >> Your ideas for modifying the Sun standard are interesting.
> >> Personally, I prefer to stick with the standard, for the reason that
> >> others have stated that it is easier for contributors to follow and
> >> creates less work modifying patches (and new code) to comply. As I
> >> said above, I would much rather see effort go into filling in the gaps
> >> and clarifying the imprecision in the content of the javadoc (both
> >> existing and that which comes with patches) than to "standardizing"
> >> format. Lets see what others in the community think.
> >
> > So, together, we say that both formatting and contents need improvement.
> > Since they are not contradicting goals, both can be achieved.
>
> Yes, though I don't see big problems with formatting and I don't see the need - and in fact see reasons not to - depart from the established standard or add more requirements that contributors need to follow.
There are no big problems, just a lot of small ones (e.g. using a keywords
like "null" without writing it as "{@code null}" and some comments being
complete sentences while others aren't).
If this is not important (again, I'm not saying it should be high-priority),
then I'd strongly suggest to remove the "trailing white space" rule from
CheckStyle because that one should be orders of magnitude less important...
> >
> > We can diverge as to their respective priority, as far as the upgrade of
> > existing code is concerned.
> > But what I'm suggesting is to lay out simple and concise rules (by
> > extracting the relevant part of the "standard", if need be) so that from now
> > on, the changes (code and doc) are provided in the best possible form.
> >
> My personal view is that the standard is fine as is. If others agree with your suggested changes and are willing to sign up for the associated maintenance, we can agree on and make changes to the Developer Guide.
The standard may be fine; it's just not applied everywhere in the doc,
that's the point: Whatever the rules, it should be easy to check a block of
Javadoc comment against the cheat sheet and to conclude that "Rule 1, 3 and
9 are violated."
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Phil Steitz <ph...@gmail.com>.
On Jan 13, 2011, at 7:21 AM, Gilles Sadowski <gi...@harfang.homelinux.org> wrote:
> Hi.
>
>> [...]
>>>
>>>> A couple of areas where we have slipped a bit over the years that I
>>>> would rather apply energy to than formatting are the following (from
>>>> the Developers' guide):
>>>>
>>>> # All component contracts must be fully specified in the javadoc
>>>> class, interface or method comments, including specification of
>>>> acceptable ranges of values, exceptions or special return values.
>>>> # External references or full statements of definitions for all
>>>> mathematical terms used in component documentation must be provided.
>>>> # Implementations should use standard algorithms and references or
>>>> full descriptions of all algorithms should be provided.
>>>> # Additions and enhancements should include updates to the User Guide.
>>>
>>> This is all OK, of course. But what I had in mind is more of a "cheat
>>> sheet", that can be checked easily by the developer (and maybe partly by
>>> CheckStyle?) so that we can be sure that the doc is both complete and a
>>> pleasant read (which, I'm convinced, is helped by a consistent form).
>>>
>>
>> Your ideas for modifying the Sun standard are interesting.
>> Personally, I prefer to stick with the standard, for the reason that
>> others have stated that it is easier for contributors to follow and
>> creates less work modifying patches (and new code) to comply. As I
>> said above, I would much rather see effort go into filling in the gaps
>> and clarifying the imprecision in the content of the javadoc (both
>> existing and that which comes with patches) than to "standardizing"
>> format. Lets see what others in the community think.
>
> So, together, we say that both formatting and contents need improvement.
> Since they are not contradicting goals, both can be achieved.
Yes, though I don't see big problems with formatting and I don't see the need - and in fact see reasons not to - depart from the established standard or add more requirements that contributors need to follow.
>
> We can diverge as to their respective priority, as far as the upgrade of
> existing code is concerned.
> But what I'm suggesting is to lay out simple and concise rules (by
> extracting the relevant part of the "standard", if need be) so that from now
> on, the changes (code and doc) are provided in the best possible form.
>
My personal view is that the standard is fine as is. If others agree with your suggested changes and are willing to sign up for the associated maintenance, we can agree on and make changes to the Developer Guide.
Phil
>
> 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] Coding and documenting guidelines
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hi.
> [...]
> >
> >> A couple of areas where we have slipped a bit over the years that I
> >> would rather apply energy to than formatting are the following (from
> >> the Developers' guide):
> >>
> >> # All component contracts must be fully specified in the javadoc
> >> class, interface or method comments, including specification of
> >> acceptable ranges of values, exceptions or special return values.
> >> # External references or full statements of definitions for all
> >> mathematical terms used in component documentation must be provided.
> >> # Implementations should use standard algorithms and references or
> >> full descriptions of all algorithms should be provided.
> >> # Additions and enhancements should include updates to the User Guide.
> >
> > This is all OK, of course. But what I had in mind is more of a "cheat
> > sheet", that can be checked easily by the developer (and maybe partly by
> > CheckStyle?) so that we can be sure that the doc is both complete and a
> > pleasant read (which, I'm convinced, is helped by a consistent form).
> >
>
> Your ideas for modifying the Sun standard are interesting.
> Personally, I prefer to stick with the standard, for the reason that
> others have stated that it is easier for contributors to follow and
> creates less work modifying patches (and new code) to comply. As I
> said above, I would much rather see effort go into filling in the gaps
> and clarifying the imprecision in the content of the javadoc (both
> existing and that which comes with patches) than to "standardizing"
> format. Lets see what others in the community think.
So, together, we say that both formatting and contents need improvement.
Since they are not contradicting goals, both can be achieved.
We can diverge as to their respective priority, as far as the upgrade of
existing code is concerned.
But what I'm suggesting is to lay out simple and concise rules (by
extracting the relevant part of the "standard", if need be) so that from now
on, the changes (code and doc) are provided in the best possible form.
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Phil Steitz <ph...@gmail.com>.
On Wed, Jan 12, 2011 at 5:32 PM, Gilles Sadowski
<gi...@harfang.homelinux.org> wrote:
> Hi.
>
>> > Is there a document presenting best practices for writing code for CM?
>> > Right now I'm thinking about the recent overwrites of Javadoc comments; so I
>> > think that it could be useful to lay out what should be there (beyond the
>> > obvious that "everything should be documented").
>>
>> Yes. See http://commons.apache.org/math/developers.html.
>> >
>> > A few things that come to mind:
>> >
>> > * All exceptions that could be thrown must be documented in a "@throws" tag,
>> > indicating all the possible causes of the exception (such as the
>> > assumed preconditions)
>>
>> +1 - tricky to do in all cases since we have abandoned checked
>> exceptions and unchecked exceptions can propagate unexpectedly through
>> API layers. I do agree with the spirit of this, though and would say
>> *must* for exceptions that may immediately be thrown as a result of
>> precondition violation. This follows from the principles laid out in
>> the Developer's Guide.
>
> This is not difficult if done immediately by the person who writes the
> original code; he knows which calls his code makes and what exceptions can
> be triggered, so he reports them in doc. Of course, for someone that come
> afterwards this is much more difficult as he will have to read through the
> whole code and track all the calls...
> That's why the "guidelines" should insist that we don't let it for the
> others...
>
+1 here - I agree completely. If we are consistent here, the code
will be maintainable. This is what is meant by the statement in the
Developer Guide that I quoted above about documenting exceptions.
>> >
>> > * The "@param" tag should not contain redundant information (such as
>> > preconditions since they must be documented in a "@throws" tag).
>>
>> For the rest of this, I would prefer that we stick with our previously
>> agreed convention (stated in the doc above) to just follow the Sun
>> conventions. It will be much easier for contributors and those
>> applying patches if we just follow the standard conventions.
>
> The problem (which I suggested to solve with _small_ a "check list" tailored
> for CM code is that the standard is sometimes not consistent (IMO), as
> examplified in this excerpt of the document you referred to:
>
> -----
> 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.
> -----
>
> I find it more esthetic to apply *one* set of rules and not one set here
> and another there; the above examples look really messy...
> So, for the "@param" tag, I prefer this set:
> * Do not use the article "the".
> * Always capitalize.
> * Write full sentences, with punctuation.
>
> Also, among the things that would make the CM doc more homogeneous, there
> would be a list of when to enclose something in a {@code ...} structure.
> And it would mention to avoid the "<code>...</code>" construct whereas it
> is suggested in the "standard" guidelines document).
>
>> A couple of areas where we have slipped a bit over the years that I
>> would rather apply energy to than formatting are the following (from
>> the Developers' guide):
>>
>> # All component contracts must be fully specified in the javadoc
>> class, interface or method comments, including specification of
>> acceptable ranges of values, exceptions or special return values.
>> # External references or full statements of definitions for all
>> mathematical terms used in component documentation must be provided.
>> # Implementations should use standard algorithms and references or
>> full descriptions of all algorithms should be provided.
>> # Additions and enhancements should include updates to the User Guide.
>
> This is all OK, of course. But what I had in mind is more of a "cheat
> sheet", that can be checked easily by the developer (and maybe partly by
> CheckStyle?) so that we can be sure that the doc is both complete and a
> pleasant read (which, I'm convinced, is helped by a consistent form).
>
Your ideas for modifying the Sun standard are interesting.
Personally, I prefer to stick with the standard, for the reason that
others have stated that it is easier for contributors to follow and
creates less work modifying patches (and new code) to comply. As I
said above, I would much rather see effort go into filling in the gaps
and clarifying the imprecision in the content of the javadoc (both
existing and that which comes with patches) than to "standardizing"
format. Lets see what others in the community think.
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] Coding and documenting guidelines
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Wed, Jan 12, 2011 at 03:23:59PM -0800, Ted Dunning wrote:
> I personally find it more aesthetic and much more expedient to use a
> standard style guide that many people are already familiar with (more or
> less, often less).
>
> Making up a new style guide is a waste of breath and subject to minor
> aesthetic quibbles like whether to use a phrase. The Sun guides are
> generally very good and where they have minor issues, the virtue of being an
> accepted standard trumps everything else. For one thing, we can do
> something productive in the code rather than argue about grammar and
> punctuation.
Maybe I was not quite clear: There is no uniformly applied style in the
Javadoc comments in Commons-Math; if there were, I wouldn't have raised the
issue (and I wouldn't have had to spend hours cleaning up inconsistent
formatting).
If aesthetic documentation were not productive, there wouldn't be editors
and publishers taking care of this aspect, and we would all be content to
read scanned manuscripts.
> On Wed, Jan 12, 2011 at 2:32 PM, Gilles Sadowski <
> gilles@harfang.homelinux.org> wrote:
>
> > I find it more esthetic to apply *one* set of rules and not one set here
> > and another there; the above examples look really messy...
> > So, for the "@param" tag, I prefer this set:
> > * Do not use the article "the".
> > * Always capitalize.
> > * Write full sentences, with punctuation.
If the above rules are not obviously clearer, more concise (and more
aesthetic) than the excerpt of the standard rules which I quoted in the
previous post, then I'm indeed wasting my breath.
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Ted Dunning <te...@gmail.com>.
I personally find it more aesthetic and much more expedient to use a
standard style guide that many people are already familiar with (more or
less, often less).
Making up a new style guide is a waste of breath and subject to minor
aesthetic quibbles like whether to use a phrase. The Sun guides are
generally very good and where they have minor issues, the virtue of being an
accepted standard trumps everything else. For one thing, we can do
something productive in the code rather than argue about grammar and
punctuation.
On Wed, Jan 12, 2011 at 2:32 PM, Gilles Sadowski <
gilles@harfang.homelinux.org> wrote:
> I find it more esthetic to apply *one* set of rules and not one set here
> and another there; the above examples look really messy...
> So, for the "@param" tag, I prefer this set:
> * Do not use the article "the".
> * Always capitalize.
> * Write full sentences, with punctuation.
>
Re: [Math] Coding and documenting guidelines
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
Hi.
> > Is there a document presenting best practices for writing code for CM?
> > Right now I'm thinking about the recent overwrites of Javadoc comments; so I
> > think that it could be useful to lay out what should be there (beyond the
> > obvious that "everything should be documented").
>
> Yes. See http://commons.apache.org/math/developers.html.
> >
> > A few things that come to mind:
> >
> > * All exceptions that could be thrown must be documented in a "@throws" tag,
> > indicating all the possible causes of the exception (such as the
> > assumed preconditions)
>
> +1 - tricky to do in all cases since we have abandoned checked
> exceptions and unchecked exceptions can propagate unexpectedly through
> API layers. I do agree with the spirit of this, though and would say
> *must* for exceptions that may immediately be thrown as a result of
> precondition violation. This follows from the principles laid out in
> the Developer's Guide.
This is not difficult if done immediately by the person who writes the
original code; he knows which calls his code makes and what exceptions can
be triggered, so he reports them in doc. Of course, for someone that come
afterwards this is much more difficult as he will have to read through the
whole code and track all the calls...
That's why the "guidelines" should insist that we don't let it for the
others...
> >
> > * The "@param" tag should not contain redundant information (such as
> > preconditions since they must be documented in a "@throws" tag).
>
> For the rest of this, I would prefer that we stick with our previously
> agreed convention (stated in the doc above) to just follow the Sun
> conventions. It will be much easier for contributors and those
> applying patches if we just follow the standard conventions.
The problem (which I suggested to solve with _small_ a "check list" tailored
for CM code is that the standard is sometimes not consistent (IMO), as
examplified in this excerpt of the document you referred to:
-----
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.
-----
I find it more esthetic to apply *one* set of rules and not one set here
and another there; the above examples look really messy...
So, for the "@param" tag, I prefer this set:
* Do not use the article "the".
* Always capitalize.
* Write full sentences, with punctuation.
Also, among the things that would make the CM doc more homogeneous, there
would be a list of when to enclose something in a {@code ...} structure.
And it would mention to avoid the "<code>...</code>" construct whereas it
is suggested in the "standard" guidelines document).
> A couple of areas where we have slipped a bit over the years that I
> would rather apply energy to than formatting are the following (from
> the Developers' guide):
>
> # All component contracts must be fully specified in the javadoc
> class, interface or method comments, including specification of
> acceptable ranges of values, exceptions or special return values.
> # External references or full statements of definitions for all
> mathematical terms used in component documentation must be provided.
> # Implementations should use standard algorithms and references or
> full descriptions of all algorithms should be provided.
> # Additions and enhancements should include updates to the User Guide.
This is all OK, of course. But what I had in mind is more of a "cheat
sheet", that can be checked easily by the developer (and maybe partly by
CheckStyle?) so that we can be sure that the doc is both complete and a
pleasant read (which, I'm convinced, is helped by a consistent form).
> [...]
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Coding and documenting guidelines
Posted by Phil Steitz <ph...@gmail.com>.
On Tue, Jan 11, 2011 at 10:15 AM, Gilles Sadowski
<gi...@harfang.homelinux.org> wrote:
> Hi.
>
> Is there a document presenting best practices for writing code for CM?
> Right now I'm thinking about the recent overwrites of Javadoc comments; so I
> think that it could be useful to lay out what should be there (beyond the
> obvious that "everything should be documented").
Yes. See http://commons.apache.org/math/developers.html.
>
> A few things that come to mind:
>
> * All exceptions that could be thrown must be documented in a "@throws" tag,
> indicating all the possible causes of the exception (such as the
> assumed preconditions)
+1 - tricky to do in all cases since we have abandoned checked
exceptions and unchecked exceptions can propagate unexpectedly through
API layers. I do agree with the spirit of this, though and would say
*must* for exceptions that may immediately be thrown as a result of
precondition violation. This follows from the principles laid out in
the Developer's Guide.
>
> * The "@param" tag should not contain redundant information (such as
> preconditions since they must be documented in a "@throws" tag).
For the rest of this, I would prefer that we stick with our previously
agreed convention (stated in the doc above) to just follow the Sun
conventions. It will be much easier for contributors and those
applying patches if we just follow the standard conventions.
A couple of areas where we have slipped a bit over the years that I
would rather apply energy to than formatting are the following (from
the Developers' guide):
# All component contracts must be fully specified in the javadoc
class, interface or method comments, including specification of
acceptable ranges of values, exceptions or special return values.
# External references or full statements of definitions for all
mathematical terms used in component documentation must be provided.
# Implementations should use standard algorithms and references or
full descriptions of all algorithms should be provided.
# Additions and enhancements should include updates to the User Guide.
I have an open action, for example, to define precisely what we mean
by "support" for distributions. What is important to me is the
content of the javadoc, not so much what elements include what info.
I think, for example, http://s.apache.org/S39 is fine. In some cases,
the preconditions of a method involve multiple parameters or other
context info so it is more convenient to state them in the main method
description. Again, the important thing is to clearly state (or
reference) a) relevant mathematical definitions and algorithms b)
preconditions and c) exceptions or NaN returns when preconditions are
not met.
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org