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

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

    [ 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