[
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
