On 1/30/11 12:42 PM, Gilles Sadowski wrote:
> On Sun, Jan 30, 2011 at 11:19:23AM -0500, Phil Steitz wrote:
>> On Sun, Jan 30, 2011 at 10:05 AM, Mikkel Meyer Andersen <m...@mikl.dk> wrote:
>>> Thanks for clearifying :).
>>> Den 30/01/2011 16.01 skrev "Gilles Sadowski" <gil...@harfang.homelinux.org>:
>>>> On Sun, Jan 30, 2011 at 02:58:43PM +0100, Mikkel Meyer Andersen wrote:
>>>>> Hi,
>>>>>
>>>>> 2011/1/30 Gilles Sadowski <gil...@harfang.homelinux.org>:
>>>>>> Hello.
>>>>>>
>>>>>>> I noticed that you have code where fields and constructor arguments
>>>>>>> have the same name. As far as I remember that is not good practise,
>>>>>>> but I might be wrong :-)?
>>>>>> Most (all?) of CM follows this convention.
>>>>> Just to be sure: Do you mean that in most of CM, parameter and field
>>>>> names coincide?
>>>> Yes.
>>>> See, for example,
>>>>
>>> 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.
> 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.
Phil
> Regards,
> Gilles
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
