commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sébastien Brisard (JIRA) <>
Subject [jira] [Commented] (MATH-852) Improvements to the Developer's Guide
Date Tue, 18 Sep 2012 06:51:07 GMT


Sébastien Brisard commented on MATH-852:

* I prefer non-closing <p> tags on a separate line, this is much more readable and takes
less space
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).

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)
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:
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Sébastien Brisard
>              Labels: formatting, guidelines
> Recent discussions (see MATH-851, as well as these threads [1|],
[2|]) 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
> 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:

View raw message