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

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
Sébastien Brisard created MATH-852:
--------------------------------------

             Summary: 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


Recent discussions 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.

--
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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)

     [ https://issues.apache.org/jira/browse/MATH-852?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Sébastien Brisard updated MATH-852:
-----------------------------------

    Description:
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.

  was:
Recent discussions 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.

   

> 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.

--
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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

     [ https://issues.apache.org/jira/browse/MATH-852?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Sébastien Brisard updated MATH-852:
-----------------------------------

    Description:
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. 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.



  was:
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.

   

> 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. 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

     [ https://issues.apache.org/jira/browse/MATH-852?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Sébastien Brisard updated MATH-852:
-----------------------------------

    Description:
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.



  was:
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. 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.



   

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Sébastien Brisard commented on MATH-852:
----------------------------------------

Here is a first addition to the *Coding style* section. What do you think?

h4. Doc comments formatting
Doc comments formatting should in general follow the [How to Write Doc Comments for the Javadoc Tool|http://www.oracle.com/technetwork/java/codeconv-138413.html] guidelines.

h5. Derogatory rules
In Commons Math, we tend to apply the following derogatory rules
* HTML tags are allowed, as long as they comply with strict XHTML specifications. Currently, the standard Javadoc Doclet does not comply with these specs, but we should get ready for this. Most notably, opening tags like {{<p>}} or {{<li>}} must end with closing tags {{</p>}} and {{</li>}}
* Even short {{@param}} comments should be capitalized and end with a period '.'. This leads to formatting which is consistent with multi-sentence comments, where the second sentence should always be capitalized.
* {{@return}} comments should _not_ be capitalized, as the corresponding comment starts with 'Returns' in the javadoc. They should end with a period '.'.
* If very short, {{@param}} (resp. {{@return}}) comments should preferably not start with 'The' (resp. 'the').
* {{@param}} and {{return}} comments should not be indented so as not to take up too much space.


Example
{noformat}
/**
 * @param x First argument.
 * @param y The second argument, always positive. This is a rather long comment,
 * which should not be indented when reaching the second line.
 * @return value.
 */
{noformat}

h5. Supplementary rules
* to be completed
               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Sébastien Brisard commented on MATH-852:
----------------------------------------

I would like to provide a link to Luc's config file for Eclipse. This file would also be the basis for a list of currently enforced formatting rules (for people who do not use Eclipse). What I'd like to know is the following: what is missing in Luc's file? In other words, what do you end up formatting by hand? The Eclipse formatter is not very flexible (I'm always struggling with it) so you _must_ be doing some things by hand...
               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Luc Maisonobe commented on MATH-852:
------------------------------------

What I am doing by hand is fix indentation for throws declaration clauses. I was never able to find a setting that was compatible with both Eclipse and checkstyle. So I end up considering checkstyle was the rule (not everybody uses Eclipse, but we all use checkstyle through maven).

Eclipse uses no indentation:
{code}
void f(int i)
throws NumberisTooLargeException {
    // some code here
}
{code}

Checkstyle uses 4 spaces indentation:
{code}
void f(int i)
    throws NumberisTooLargeException {
    // some code here
}
{code}

               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Sébastien Brisard commented on MATH-852:
----------------------------------------

{quote}
So I end up considering checkstyle was the rule [...]
{quote}

I'm confused, now: I was not aware of checkstyle ever complaining about that. Could you please elaborate (I had a quick check this morning, and Checkstyle was indeed silent).
               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Luc Maisonobe commented on MATH-852:
------------------------------------

My bad, sorry.
I made a confusion with the checkstyle setting for Orekit, where we have the following setting:
{code:xml}
        <module name="Indentation">
            <property name="basicOffset" value="4"/>
            <property name="caseIndent" value="0"/>
        </module>
{code}

We don't have this setting in [math].
               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Thomas Neidhart commented on MATH-852:
--------------------------------------

Regarding the javadoc formatting, I like the formatting proposed in the [Javadoc Tutorial|http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html], see an example:

{noformat}
/**
 * Returns an Image object that can then be painted on the screen.
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument.
 * <p>
 * This method always returns immediately, whether or not the
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives
 * that draw the image will incrementally paint on the screen.
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }
{noformat}

Some comments on the rules:

 * I prefer non-closing <p> tags on a separate line, this is much more readable and takes less space
 * @param and @return comments should not require a closing period

Regarding the example:

{noformat}
/**
 * @param x First argument.
 * @param y The second argument, always positive. This is a rather long comment,
 * which should not be indented when reaching the second line.
 * @return value.
 */
{noformat}

I am not sure about the indentation of the long comment, but I normally use two spaces in the next line to make a better distinction with the next tag, like this (but could also use more spaces):

{noformat}
/**
 * @param x First argument.
 * @param y The second argument, always positive. This is a rather long comment,
 *   which should not be indented when reaching the second line.
 * @return value.
 */
{noformat}
               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Sébastien Brisard commented on MATH-852:
----------------------------------------

{quote}
* I prefer non-closing <p> tags on a separate line, this is much more readable and takes less space
{quote}
The reason why I proposed this rule is that I think we should be ready for xhtml (which is again not yet enforced by the standard doclet). For example, including some MathML in the javadoc would require strict xhtml. I'm using mathml in some other projects (I know I should be writing a user's guide instead...). However, I'm not sure that it will be ever used in Commons-Math, so I'm happy with this proposal (or even better: no rule at all).

{quote}
I am not sure about the indentation of the long comment, but I normally use two spaces in the next line to make a better distinction with the next tag, like this (but could also use more spaces)
{quote}
This is merely reflecting what's currently done in the library. I previously used the formatting suggested in the tutorial you've pointed at, but it must be owned that you get used very quickly to the CM common practice.
               

> 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Gilles commented on MATH-852:
-----------------------------

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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

    [ 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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Thomas Neidhart commented on MATH-852:
--------------------------------------

If the goal is to have proper formatted XHTML, than I am fine with this, and we should have </p> tags as well.

@punctuation: I like the approach in the javadoc tutorial, that one line fragments are not ended with a period whereas if there is an additional description, they are separated by a period and the final sentence also ends with a period. Keep in mind that most @param descriptions are not really sentences:

{noformat}
 * @param text1  the text of the tool tip
 * @param text1  the string to display.  If the text is null,
 *               the tool tip is turned off for this component.
{noformat}

@indentation: the rule is actually quite simply and derived from the need to have readable javadoc in your IDE (in the browser it does not matter, as the javadoc tool formats it for you). When there are lots of @param, @throws and a @return tag with long descriptions this can easily lead to a wall of text that is very difficult to read. The indentation is there to easily separate the different tags with your eye. Whether you use 2 or more spaces depends what you prefer (I think the default formatter in eclipse puts a fixed indentation at position 19/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é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
Reply | Threaded
Open this post in threaded view
|

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

AD_LB (Jira)
In reply to this post by AD_LB (Jira)

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

Gilles commented on MATH-852:
-----------------------------

bq. I like the approach in the javadoc tutorial [...]

Please note that the Java API docs do not seem to follow this tutorial (at least not consistently): many single-line "@param" descriptions end with a period!

bq. [...] one line fragments are not ended with a period whereas if there is an additional description, they are separated by a period [...]

I simply don't like something that looks like the result of laziness. Why do 2 different things when the difference is just adding a "."?

For the indentation, it's a practical argument. As I said, your example looks nice until one will have to e.g. change the name of one of the parameters: the alignment will be broken and to recover it, you might have to touch things that wouldn't have been without this alignment requirement (consequently: more lines changed in the commit)...

This is nicely aligned:
{noformat}
 * @param text1  the text of the tool tip
 * @param text1  the string to display.  If the text is null,
 *               the tool tip is turned off for this component.
{noformat}

Oh, you made a copy/paste mistake: the parameter names. I'm going to fix the doc:
{noformat}
 * @param textForSpeed  the text of the tool tip
 * @param textForAcceleration  the string to display.  If the text is null,
 *               the tool tip is turned off for this component.
{noformat}

Oops.

And (since we aim for fully illustrative parameter names), we are going to have a lot of quite large gaps
and lines pushed far to the right:
{noformat}
 * @param textForSpeed         the text of the tool tip
 * @param textForAcceleration  the string to display.  If the text is null,
 *                             the tool tip is turned off for this component.
{noformat}

Please note: I agree that it is looking nicer, but "nice" is the goal of the _formatted_ docs. Within the code, we should aim for "simple", and just as readable as any piece of text which we are used to read.
Comments are supposed to be a plain English description of some code; I don't see the point in trying to invent a new English syntax and punctuation system. ;)

               

> 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