> >>>>
> >>> src/main/java/org/apache/commons/math/ode/nonstiff/AdaptiveStepsizeIntegrator.java
> >>>> src/main/java/org/apache/commons/math/geometry/Rotation.java
> >>>> I think that the list is quite long...
> >>>>
> >> When what is being set is exactly the field value and this name makes
> >> sense in the public constructor, I see nothing wrong with it. As
> >> Stephen said, IDEs and static analyzers will ensure that we do not
> >> omit the reference to the instance. What is more important is that
> >> the field and parameter names be meaningful and well-documented.
> > (Also answering one of your other post questions.)
> > The rationale behind the parameter names is that they correpond to those
> > used in the advertised link.
> > This make it easy to compare the code with the reference.
> > Also there are not meaningful _short_ names for those and using long names
> > makes the formula in the "value" method quite unreadable.
> > One parameter name would be
> > "parameterThatAffectsNearWhichAsymptoteMaximumGrowthOccurs"
> I would suggest giving this a little thought. In Java, we favor
> full words as variable names, especially those that appear in public
> APIs. Certainly "upperAsymptote, "lowerAsymptote" and "growthRate"
> (pretty much directly from the javadoc comments describing these
> parameters) would be improvements over single letters for those fields.
I don't think so, for the reasons I gave.
I also already mentioned what I thought of piling up redundancy in the
Javadoc. This is the same; IMHO, you loose clarity when writing
/**
* @param lowerAsymptote Lower asymptote.
* @param upperAsymptote Upper asymptote.
* @param growthRate Growth rate.
*/
And so on...
But I'm not against you changing it if you think you have interesting
alternative names and it would make you feel better!
> > The reference did not provide meaningful or standard names so I preferred to
> > stick to those letters that appear in the formula (except for changing the
> > Greek "nu" to "n").
> >
> > A more meaningful way of documenting methematical formulae would be to
> > introduce LaTeX formatting:
> > /**
> > * <pre>
> > * <div class="latex">
> > * y(x) = a + \frac{k - a}{(1 + q e^{-b (x - m)})^{1 / \nu}}
> > * </div>
> > * </pre>
> > */
> >
> -1 for introduce the monstrosity of Tex into our javadoc. It is
> fine to use external references for formulas too complex to be
> easily represented in HTML. This one is a borderline case.
> > However we should agree on the exact formatting so that processing of the
> > documentation might possibly create a PNG file showing the formula.
> > [Something else to be put into the "unneeded" coding and documenting
> > guidelines which I proposed a few weeks ago...]
> >
> -1 for managing png's as essential components of the javadoc. It is
> also very desirable to be able to read and make sense of the javadoc
> in the source files.
Talking about monstrosity, HTML beats LaTeX by far (IMHO).
The rule could be that only single formula can documented with LaTeX.
My proposal is in line with using "xml" in the user guide. Instead of LaTeX
it could some other markup language that can properly represents
mathematical notation. I'm afraid that LaTeX is the most readable of all.
A tool would able to automatically convert the <chosen_format> into an image
for inclusion in the generated documention (as is done for the user manual).
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
