commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gilles (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (MATH-852) Improvements to the Developer's Guide
Date Tue, 18 Sep 2012 12:20:08 GMT

    [ 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

Mime
View raw message