Mailing-List: contact issues-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: issues@commons.apache.org
Date: Tue, 18 Sep 2012 22:08:08 +1100 (NCT)
From: "Gilles (JIRA)" <jira@apache.org>
To: issues@commons.apache.org
Message-ID: <2145786621.91801.1347966488605.JavaMail.jiratomcat@arcas>
In-Reply-To: <747443963.15054.1346297407573.JavaMail.jiratomcat@arcas>
Subject: [jira] [Comment Edited] (MATH-852) Improvements to the Developer's
 Guide
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable


    [ https://issues.apache.org/jira/browse/MATH-852?page=3Dcom.atlassian.j=
ira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=3D134577=
36#comment-13457736 ]=20

Gilles edited comment on MATH-852 at 9/18/12 10:07 PM:
-------------------------------------------------------

bq. I prefer non-closing <p> tags on a separate line, this is much more rea=
dable and takes less space

I'm not sure I understand the example of this usage. Did you intend to use =
it as a line break?
Like S=C3=A9bastien, I think that we should enforce XHTML (strict XML synta=
x).
But I also think that paragraphs ("<p>...</p>" constructs) are mostly dispe=
nsable in Javadoc. When there is only one paragraph, they take space for no=
thing. Where there are more paragraphs, I almost never see the usefulness o=
f a blank line separating them: IMO, a line break ("<br/>") would be suffic=
ient.

bq. @param and @return comments should not require a closing period

As I've explained several times, this is not consistent as correct sentence=
s end with a period. What would you do if more than one sentence is needed?=
 If you'd use a period in that case, then why not use it  in every case? Th=
is avoids having to explain rule variations.

IMHO, its also holds for capitalization of the first word of a sentence, e.=
g. uppercasing the first letter of incomplete sentences (like is often the =
case for the "@param" tag).

Here are my preferred choices:

(x) I don't like:
{noformat}
 * @param y The second argument, always positive. This is a rather long com=
ment,
 * which should not be indented when reaching the second line.
{noformat}

(/) I like:
{noformat}
 * @param y Second argument, always positive. This is a rather long comment=
,
 * which should not be indented when reaching the second line.
{noformat}

(/)(/) I like this better:
{noformat}
 * @param y Second argument, always positive.
 * This is a rather long comment, which should not be indented when reachin=
g
 * the second line but should be wrapped so that lines are not much longer =
than
 * about 72 characters.
{noformat}

(x) I don't like:
{noformat}
 * @return result of the computation.
{noformat}

(/) I like:
{noformat}
 * @return the result of the computation.
{noformat}

Yes, here I advocate for having "the" because the reading is then natural i=
f you assume that the sentence starts with the verb "returns" (as appears i=
n the formatted Javadoc pages).

bq. I am not sure about the indentation of the long comment, but I normally=
 use two spaces [...]

IMHO, this is a kind of rule impossible to understand ("Why two?", "Why not=
 three?").
One character is understandable, as a visual separation from the leading "*=
".

Also, trying to align on the previous line (parameter names and/or paramete=
r description is not a streamline process: you have to anticipate all subse=
quent lines, and apply a number of spaces that will match the longest one (=
and then, if you guessed wrong, or following a Javadoc update, you'll have =
to touch everything so that it is again nicely aligned).

I think that the Javadoc should not have any ASCII formatting beyond making=
 it easy to read when looking at the code, i.e. the same rules as for a lit=
erary work should apply:
* Not too many characters on the same line.
* No indentation of the following line(s).
* A single space to separate words.
* A sentence starts with an upper-case letter and ends with a period.
* Avoid abbreviations and "telegraphic" style.

               =20
      was (Author: erans):
    bq. I prefer non-closing <p> tags on a separate line, this is much more=
 readable and takes less space

I'm not sure I understand the example of this usage. Did you intend to use =
it as a line break?
Like S=C3=A9bastien, I think that we should enforce XHTML (strict XML synta=
x).
But I also think that paragraphs ("<p>...</p>" constructs) are mostly dispe=
nsable in Javadoc. When there is only one paragraph, they take space for no=
thing. Where there are more paragraphs, I almost never see the usefulness o=
f a blank line separating them: IMO, a line break ("<br/>") would be suffic=
ient.

bq. @param and @return comments should not require a closing period

As I've explained several times, this is not consistent as correct sentence=
s end with a period. What would you do if more than one sentence is needed?=
 If you'd use a period in that case, then why not use it  in every case? Th=
is avoids having to explain rule variations.

IMHO, its also holds for capitalization of the first word of a sentence, e.=
g. uppercasing the first letter of incomplete sentences (like is often the =
case for the "@param" tag).

Here are my preferred choices:

(x) I don't like:
{noformat}
 * @param y The second argument, always positive. This is a rather long com=
ment,
 * which should not be indented when reaching the second line.
{noformat}

(/) I like:
{noformat}
 * @param y Second argument, always positive. This is a rather long comment=
,
 * which should not be indented when reaching the second line.
{noformat}

(/)(/) I like this better:
{noformat}
 * @param y Second argument, always positive.
 * This is a rather long comment, which should not be indented when reachin=
g
 * the second line but should be wrapped so that lines are not much longer =
than
 * about 72 characters.
{noformat}

(x) I don't like:
{noformat}
 * @return result of the computation.
{noformat}

(/) I like:
{noformat}
 * @return the result value of the computation.
{noformat}

Yes, here I advocate for having "the" because the reading is then natural i=
f you assume that the sentence starts with the verb "returns" (as appears i=
n the formatted Javadoc pages).

bq. I am not sure about the indentation of the long comment, but I normally=
 use two spaces [...]

IMHO, this is a kind of rule impossible to understand ("Why two?", "Why not=
 three?").
One character is understandable, as a visual separation from the leading "*=
".

Also, trying to align on the previous line (parameter names and/or paramete=
r description is not a streamline process: you have to anticipate all subse=
quent lines, and apply a number of spaces that will match the longest one (=
and then, if you guessed wrong, or following a Javadoc update, you'll have =
to touch everything so that it is again nicely aligned).

I think that the Javadoc should not have any ASCII formatting beyond making=
 it easy to read when looking at the code, i.e. the same rules as for a lit=
erary work should apply:
* Not too many characters on the same line.
* No indentation of the following line(s).
* A single space to separate words.
* A sentence starts with an upper-case letter and ends with a period.
* Avoid abbreviations and "telegraphic" style.

                 =20
> Improvements to the Developer's Guide
> -------------------------------------
>
>                 Key: MATH-852
>                 URL: https://issues.apache.org/jira/browse/MATH-852
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: S=C3=A9bastien Brisard
>              Labels: formatting, guidelines
>
> Recent discussions (see MATH-851, as well as these threads [1|http://mark=
mail.org/thread/utxuipyolpnche5o], [2|http://markmail.org/thread/sma3nwa5j3=
hspvp5]) have shown that our actual requirements (especially regarding form=
atting) are higher than stated in the Developer's Guide. This leads to conf=
usion among new contributors, as well as recent committers. It is therefore=
 proposed to revise this guide, in order for it to reflect the actual expec=
tations regarding submitted code.
> This guide should however not act as a deterrent for new contributors, so=
 attention should be paid to "rules" we consider as essential vs. superfluo=
us rules.
> Here is an extract of the developer's guide in its current state
> h3. Coding Style
> Commons Math follows [Code Conventions for the Java Programming Language|=
http://www.oracle.com/technetwork/java/codeconv-138413.html]. As part of th=
e maven build process, style checking is performed using the Checkstyle plu=
gin, using the properties specified in checkstyle.xml. Committed code shoul=
d generate no Checkstyle errors. One thing that Checkstyle will complain ab=
out is tabs included in the source code. Please make sure to set your IDE o=
r editor to use spaces instead of tabs.
> Committers should make sure that svn properties are correctly set on file=
s added to the repository. See the section on Committer Subversion Access o=
n the Apache Source Code Repositories page.
> h3. Documentation
> * Committed code must include full javadoc.
> * All component contracts must be fully specified in the javadoc class, i=
nterface or method comments, including specification of acceptable ranges o=
f values, exceptions or special return values.
> * External references or full statements of definitions for all mathemati=
cal terms used in component documentation must be provided.
> * Implementations should use standard algorithms and references or full d=
escriptions of all algorithms should be provided.
> * Additions and enhancements should include updates to the User Guide.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrato=
rs
For more information on JIRA, see: http://www.atlassian.com/software/jira