[Numbers] API of "Complex"

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

[Numbers] API of "Complex"

Gilles Sadowski
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)

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?

Regards,
Gilles


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] API of "Complex"

Gilles Sadowski
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] API of "Complex"

garydgregory
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.

Gary


On Thu, Feb 1, 2018 at 7:07 AM, Gilles <[hidden email]> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] API of "Complex"

jodastephen
On 1 February 2018 at 15:30, Gary Gregory <[hidden email]> wrote:
> 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)

In JSR-310, of() is used when there is little work performed in the
factory, and relatively low chance of an error. from() is used when
performing a complex conversion, that has a higher chance of failure,

Stephen

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] API of "Complex"

garydgregory
On Thu, Feb 1, 2018 at 9:59 AM, Stephen Colebourne <[hidden email]>
wrote:

> On 1 February 2018 at 15:30, Gary Gregory <[hidden email]> wrote:
> > 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)
>
> In JSR-310, of() is used when there is little work performed in the
> factory, and relatively low chance of an error. from() is used when
> performing a complex conversion, that has a higher chance of failure,
>

I like that. To me from() implies some sort of conversion, and of() a
simple construction.


>
> Stephen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] API of "Complex"

Gilles Sadowski
On Thu, 1 Feb 2018 10:41:58 -0700, Gary Gregory wrote:

> On Thu, Feb 1, 2018 at 9:59 AM, Stephen Colebourne
> <[hidden email]>
> wrote:
>
>> On 1 February 2018 at 15:30, Gary Gregory <[hidden email]>
>> wrote:
>> > 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)
>>
>> In JSR-310, of() is used when there is little work performed in the
>> factory, and relatively low chance of an error. from() is used when
>> performing a complex conversion, that has a higher chance of
>> failure,
>>
>
> I like that. To me from() implies some sort of conversion, and of() a
> simple construction.
>

Isn't the difference between those an "implementation detail"?
What if the implementation changes?  E.g. we add fields and what
was a "conversion" becomes a "simple" construction...

IMO a consistent naming is valuable in itself.
If a developer is worried about performance hits of (from?)
"conversion", there is always the source. :-)

Note that in this particular case of "Complex", the proposed
"of" methods imply little work and low risk of failure (which
would result from a programming error).

Gilles


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[Numbers] Make "Complex" a "final" class? (Was: [...] API of "Complex")

Gilles Sadowski
In reply to this post by garydgregory
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 <[hidden email]>
> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] Make "Complex" a "final" class? (Was: [...] API of "Complex")

jodastephen
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 <[hidden email]> 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 <[hidden email]>
>> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [Numbers] Make "Complex" a "final" class?

Gilles Sadowski
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 <[hidden email]>
> 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
>>> <[hidden email]>
>>> 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: [hidden email]
For additional commands, e-mail: [hidden email]