You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles <gi...@harfang.homelinux.org> on 2018/02/02 12:45:29 UTC
[Numbers] Make "Complex" a "final" class? (Was: [...] API of "Complex")
On Thu, 1 Feb 2018 08:30:00 -0700, Gary Gregory wrote:
> Hi All:
>
> I like the "of" prefix but I think it might be odd to force the
> convention
> for ALL factories. It might be an English language thing for me.
>
> For example, (picking a made up example) this reads really well to
> me:
> Pair.of(foo, bar) because that what you'd use in spoken English.
>
> OTOH, this does not read well to me: Fraction.of(num, denum); this
> would be
> better: Fraction.from(num, denum)
>
> All of this to say that we should make sure that the factory method
> "reads
> well" for that class. I know it might feel subjective.
>
> I like the idea of a private ctor but it does not have to be unique
> in my
> mind. Sure, it's nice if there is one.
>
> I also like the idea of the ctor being private because we can open it
> up
> later to protected if we want to allow for subclassing.
>
> I would also consider making classes final, especially if the ctor is
> private.
Any caveat on doing that? Is this a final (!) decision or can one
change one's mind in a later release?
What are the benefits?
Thanks,
Gilles
>
> Gary
>
>
> On Thu, Feb 1, 2018 at 7:07 AM, Gilles <gi...@harfang.homelinux.org>
> wrote:
>
>> On Thu, 01 Feb 2018 13:59:13 +0100, Gilles wrote:
>>
>>> Hi.
>>>
>>> IMHO, there are too many accessor and factory methods.
>>> We should strive for a lean and consistent API.
>>>
>>> For the factory methods, I suggest the "of" convention:
>>> public static Complex ofCartesian(double re, double im)
>>> public static Complex ofPolar(double abs, double arg)
>>> And, as syntactic sugar:
>>> public static Complex ofCis(double arg)
>>>
>>
>> Those are useful too:
>> public ofReal(double re)
>> public ofImaginary(double im)
>>
>>
>>> For the accessors:
>>> public double re() { return real }
>>> public double im() { return imaginary }
>>>
>>> I'd have
>>> public double arg()
>>> public double abs()
>>> in order to compute the polar coordinates.
>>>
>>> I'm -0 to have others as syntactic sugar since they are
>>> misleading (a.o. when "implying" the read of a field when
>>> a computation is performed).
>>>
>>> WDYT?
>>>
>>
>> In addition to the above, I propose
>> * to have a single, "private", constructor:
>> private Complex(double re, double im)
>> * to remove the "protected" method "createComplex" (
>> unless there is a case for inheritance).
>>
>> Regards,
>> Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Numbers] Make "Complex" a "final" class?
Posted by Gilles <gi...@harfang.homelinux.org>.
On Fri, 2 Feb 2018 13:20:21 +0000, Stephen Colebourne wrote:
> Some of the classes you are talking about are what I call VALJOs.
> Follow these guidelines and your class will be well placed for the
> future.
> http://blog.joda.org/2014/03/valjos-value-java-objects.html
Thanks.
In that post, you mention "final" in this sentence:
---CUT---
The class must be immutable, which implies the final keyword
and thread-safety.
---CUT---
Do you mean that the *class* must be declared "final"?
A class can be immutable without being "final", can't it?
Or is the requirement necessary for future optimization of
value objects?
Regards,
Gilles
> Stephen
>
> On 2 February 2018 at 12:45, Gilles <gi...@harfang.homelinux.org>
> wrote:
>> On Thu, 1 Feb 2018 08:30:00 -0700, Gary Gregory wrote:
>>>
>>> Hi All:
>>>
>>> I like the "of" prefix but I think it might be odd to force the
>>> convention
>>> for ALL factories. It might be an English language thing for me.
>>>
>>> For example, (picking a made up example) this reads really well to
>>> me:
>>> Pair.of(foo, bar) because that what you'd use in spoken English.
>>>
>>> OTOH, this does not read well to me: Fraction.of(num, denum); this
>>> would
>>> be
>>> better: Fraction.from(num, denum)
>>>
>>> All of this to say that we should make sure that the factory method
>>> "reads
>>> well" for that class. I know it might feel subjective.
>>>
>>> I like the idea of a private ctor but it does not have to be unique
>>> in my
>>> mind. Sure, it's nice if there is one.
>>>
>>> I also like the idea of the ctor being private because we can open
>>> it up
>>> later to protected if we want to allow for subclassing.
>>>
>>> I would also consider making classes final, especially if the ctor
>>> is
>>> private.
>>
>>
>> Any caveat on doing that? Is this a final (!) decision or can one
>> change one's mind in a later release?
>> What are the benefits?
>>
>> Thanks,
>> Gilles
>>
>>>
>>> Gary
>>>
>>>
>>> On Thu, Feb 1, 2018 at 7:07 AM, Gilles
>>> <gi...@harfang.homelinux.org>
>>> wrote:
>>>
>>>> On Thu, 01 Feb 2018 13:59:13 +0100, Gilles wrote:
>>>>
>>>>> Hi.
>>>>>
>>>>> IMHO, there are too many accessor and factory methods.
>>>>> We should strive for a lean and consistent API.
>>>>>
>>>>> For the factory methods, I suggest the "of" convention:
>>>>> public static Complex ofCartesian(double re, double im)
>>>>> public static Complex ofPolar(double abs, double arg)
>>>>> And, as syntactic sugar:
>>>>> public static Complex ofCis(double arg)
>>>>>
>>>>
>>>> Those are useful too:
>>>> public ofReal(double re)
>>>> public ofImaginary(double im)
>>>>
>>>>
>>>>> For the accessors:
>>>>> public double re() { return real }
>>>>> public double im() { return imaginary }
>>>>>
>>>>> I'd have
>>>>> public double arg()
>>>>> public double abs()
>>>>> in order to compute the polar coordinates.
>>>>>
>>>>> I'm -0 to have others as syntactic sugar since they are
>>>>> misleading (a.o. when "implying" the read of a field when
>>>>> a computation is performed).
>>>>>
>>>>> WDYT?
>>>>>
>>>>
>>>> In addition to the above, I propose
>>>> * to have a single, "private", constructor:
>>>> private Complex(double re, double im)
>>>> * to remove the "protected" method "createComplex" (
>>>> unless there is a case for inheritance).
>>>>
>>>> Regards,
>>>> Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Numbers] Make "Complex" a "final" class? (Was: [...] API of "Complex")
Posted by Stephen Colebourne <sc...@joda.org>.
Some of the classes you are talking about are what I call VALJOs.
Follow these guidelines and your class will be well placed for the
future.
http://blog.joda.org/2014/03/valjos-value-java-objects.html
Stephen
On 2 February 2018 at 12:45, Gilles <gi...@harfang.homelinux.org> wrote:
> On Thu, 1 Feb 2018 08:30:00 -0700, Gary Gregory wrote:
>>
>> Hi All:
>>
>> I like the "of" prefix but I think it might be odd to force the convention
>> for ALL factories. It might be an English language thing for me.
>>
>> For example, (picking a made up example) this reads really well to me:
>> Pair.of(foo, bar) because that what you'd use in spoken English.
>>
>> OTOH, this does not read well to me: Fraction.of(num, denum); this would
>> be
>> better: Fraction.from(num, denum)
>>
>> All of this to say that we should make sure that the factory method "reads
>> well" for that class. I know it might feel subjective.
>>
>> I like the idea of a private ctor but it does not have to be unique in my
>> mind. Sure, it's nice if there is one.
>>
>> I also like the idea of the ctor being private because we can open it up
>> later to protected if we want to allow for subclassing.
>>
>> I would also consider making classes final, especially if the ctor is
>> private.
>
>
> Any caveat on doing that? Is this a final (!) decision or can one
> change one's mind in a later release?
> What are the benefits?
>
> Thanks,
> Gilles
>
>>
>> Gary
>>
>>
>> On Thu, Feb 1, 2018 at 7:07 AM, Gilles <gi...@harfang.homelinux.org>
>> wrote:
>>
>>> On Thu, 01 Feb 2018 13:59:13 +0100, Gilles wrote:
>>>
>>>> Hi.
>>>>
>>>> IMHO, there are too many accessor and factory methods.
>>>> We should strive for a lean and consistent API.
>>>>
>>>> For the factory methods, I suggest the "of" convention:
>>>> public static Complex ofCartesian(double re, double im)
>>>> public static Complex ofPolar(double abs, double arg)
>>>> And, as syntactic sugar:
>>>> public static Complex ofCis(double arg)
>>>>
>>>
>>> Those are useful too:
>>> public ofReal(double re)
>>> public ofImaginary(double im)
>>>
>>>
>>>> For the accessors:
>>>> public double re() { return real }
>>>> public double im() { return imaginary }
>>>>
>>>> I'd have
>>>> public double arg()
>>>> public double abs()
>>>> in order to compute the polar coordinates.
>>>>
>>>> I'm -0 to have others as syntactic sugar since they are
>>>> misleading (a.o. when "implying" the read of a field when
>>>> a computation is performed).
>>>>
>>>> WDYT?
>>>>
>>>
>>> In addition to the above, I propose
>>> * to have a single, "private", constructor:
>>> private Complex(double re, double im)
>>> * to remove the "protected" method "createComplex" (
>>> unless there is a case for inheritance).
>>>
>>> Regards,
>>> Gilles
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org