[
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
