[jira] [Comment Edited] (MATH-852) Improvements to the Developer's Guide

["Gilles (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/MATH-852?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13457736#comment-13457736 ] 

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 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ébastien, I think that we should enforce XHTML (strict XML syntax).
But I also think that paragraphs ("<p>...</p>" constructs) are mostly dispensable in Javadoc. When there is only one paragraph, they take space for nothing. Where there are more paragraphs, I almost never see the usefulness of a blank line separating them: IMO, a line break ("<br/>") would be sufficient.

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

As I've explained several times, this is not consistent as correct sentences 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? This 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 comment,
 * 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 reaching
 * 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 if you assume that the sentence starts with the verb "returns" (as appears in 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 parameter description is not a streamline process: you have to anticipate all subsequent 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 literary 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.

                
      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ébastien, I think that we should enforce XHTML (strict XML syntax).
But I also think that paragraphs ("<p>...</p>" constructs) are mostly dispensable in Javadoc. When there is only one paragraph, they take space for nothing. Where there are more paragraphs, I almost never see the usefulness of a blank line separating them: IMO, a line break ("<br/>") would be sufficient.

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

As I've explained several times, this is not consistent as correct sentences 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? This 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 comment,
 * 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 reaching
 * 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 if you assume that the sentence starts with the verb "returns" (as appears in 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 parameter description is not a streamline process: you have to anticipate all subsequent 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 literary 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.

                  
> 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ébastien Brisard
>              Labels: formatting, guidelines
>
> Recent discussions (see MATH-851, as well as these threads [1|http://markmail.org/thread/utxuipyolpnche5o], [2|http://markmail.org/thread/sma3nwa5j3hspvp5]) have shown that our actual requirements (especially regarding formatting) are higher than stated in the Developer's Guide. This leads to confusion among new contributors, as well as recent committers. It is therefore proposed to revise this guide, in order for it to reflect the actual expectations 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. superfluous 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 the maven build process, style checking is performed using the Checkstyle plugin, using the properties specified in checkstyle.xml. Committed code should generate no Checkstyle errors. One thing that Checkstyle will complain about is tabs included in the source code. Please make sure to set your IDE or editor to use spaces instead of tabs.
> Committers should make sure that svn properties are correctly set on files added to the repository. See the section on Committer Subversion Access on 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, 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 message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira