[phobos] Time to get ready for the next release

[Steve Schveighoffer]

I'm consolidating responses here...



----- Original Message -----
> From: Robert Jacques <sandford at jhu.edu>

> On Mon, 25 Apr 2011 09:47:32 -0400, Steve Schveighoffer 
> <schveiguy at yahoo.com> wrote:
>>  It's impossible to improve the design when the compiler doesn't let 
> you enforce your design!
>> 
>>  And no, the user is not always right.  That's why we have the compiler 
> to tell them so ;)
> 
> Having D enforce your design, can not _ever_ improve a design. Every single time 
> DMD rapts the user's knuckles enforcing your design, it is an instance where 
> your design failed. It is a safety net. Nothing more.

Incorrect.  DMD enforces you use the names the author designed, with the capitalization the author designed.  If you do not, it doesn't compile.  It is no different with parentheses, which are part of the name.

> Have a safety net is important, but the more it extends out beyond the concrete 
> of invalid and meaningless code, the more it encourages mediocre design. And any 
> fall into the safety net still hurts.

It hurts when you're not allowed to write confusing code?  That sounds like a pretty good design to me :)

>>  What I meant was, the technicality that the function could be pure, and 
> that would remove the possibility of using it the "wrong way" does not 
> invalidate the property problem.  In fact, it does not necessarily invalidate 
> the example, since it is D1 we are talking about here (Tango).
> 
> I don't think in terms of a single property problem (I don't even know 
> what you mean by that). I think in terms of many small problems of varying 
> severity. (And this solves the vast majority of the high severity issues) And 
> any solution to the 'property problem' would be D2/D3 only, so I 
> don't know why you're mentioning D1.

I'm referring to the ability to call any method with the right arguments as properties.  This exists in D1 and currently in D2 (to be deprecated).


>>  But in any case, this is diverging into the obscure.  I don't think 
> rules that try to guess what the author is intending are as good as annotations 
> which tell the compiler what the author is intending.
> 
> Of course not, but there's a reason that most cars are automatics: there is 
> a non-negligible cost to using a heavy annotation based system. The question 
> isn't so much as is one 'better' or not, but is it good enough most 
> of the time?

Most of the time isn't good enough.  Is it ok if the compiler's code 
generation works "most of the time"?  If the compiler allows me to get 
the design I want most of the time, and other times it's impossible, 
that is a half-ass flawed design, and it's actually worse than not 
having @property at all.

> There are problems with using @property alone. There are problem with using 
> Methods-as-Fields alone. This would indicate that some compromise is needed, and 
> therefore every point of the synthesis/trade-off curve is valuable. (Or 
> alternatively that we need to scrape both and start a fresh)

But the problem with enforcing @property is just that you don't want to name
 your functions differently from the properties.  It's not that the 
functionality cannot be had.  Essentially, it's a bikeshed problem, not a
 real problem.

>>  For you to reject my rebuttal of your obviously abstract example by saying 
> my rebuttal is too abstract is also fallacious.
> 
> *sigh* The original argument was "Here is an API design, A, that you 
> can't express elegantly with @property alone". Your rebuttal was 
> "Well, your abstracted example is obviously of Poor Design (TM), you should 
> use B instead. Therefore, this 'issue' with @property, isn't really 
> an issue". Your rebuttal introduced a new argument (that A was bad design, 
> so use B instead) and I was pointing out the flaws in you making that argument 
> based on abstracted information. The original argument was never about the 
> 'goodness' of A, it was about the ability to express A in the first 
> place; the biggest flaw in your argument is that the ability to express 
> 'poor' design should warrant the removal of the ability to express it.

*double sigh* So essentially, you put forth an argument showing how you 
are correct using abstract data, and you reject my rebuttal that uses 
the same abstract data because... it's abstract?  Give me a break!  Is 
your argument impervious to attack then, because it's abstract?

In all concrete examples that exist, if this compiles:

a = b.x = c;

Where x is a property name, I would expect a == c.  Any reasonable programmer would.

Look, the problem is not about what you are thinking when you write it, 
it's what you are thinking when you read it.  Essentially, your design 
promotes confusing/unreviewable code, i.e. it's design could be improved.

>>  No they don't.  This is a common argument against larger APIs.  I know 
> many many APIs where I don't *know* the whole API, I just know what I need 
> to get my work done, and lookup anything else.  If you want to use the setX 
> version all the time, there is no need to learn the property functions.  In 
> fact, there is no more learning required for the setX version and the dual 
> property/function version -- both have the same number of API calls.
>> 
>>  Bottom line, increasing the number of documented calls does not make it 
> harder to learn one of those calls.
> 
> I'm not arguing for or against larger APIs. My issue is with inefficient 
> APIs. With dual property/function I can store a single entity in my mind (or in 
> the docs) and then apply language rules to get 2 API calls. In the alternative, 
> I have to store 3 entities, the two names and their relationship to each other, 
> to get 2 API calls.

No you don't.  You only have to store the relationship "if I want to use
 this as a property, use x.  If I want to use it using fluent 
programming, use setX()", then you just have to remember the names for 
the properties.  It's no different than the relationship "If I want to 
use this as a property, use x.  If I want to use it using fluent 
programming use x()".  You actually will not notice a difference, I 
guarantee your brain will not run out of space because of this :)

The docs can state the same relationship in one spot, or just use ///ditto to group both the property and the setter together.

> 
>>>  3) If setProp actually read better in real life, we'd use it. But 
> it
>>>  doesn't, so we aren't. By the way, I would hazard that 
> setX/getX are one
>>>  of the most famous/infamous pieces of API design out there and that 
> everyone
>>>  can/does consider it.
>> 
>>  Your opinion.  I have used it, and have had no complaints.
> 
> I'm not sure what you're implying/responding to here. 

I was responding to "If setProp actually read better in real life, we'd 
use it.  But it doesn't, so we aren't."  Sorry, did you think that was a fact and not an opinion?

> My response was 
> was that I (and almost everyone else) has used setX/getX at some point and 
> always considers whether its the best choice for job (or not) and that implying 
> that we didn't consider it during API design seems a bit condescending, nor 
> is it really helpful to the discussion.

I do not know your reasons for your design.  All I can guess is that you
 did not consider the possibilities for abuse, or the confusion of the 
reviewer, or thought they were not important, and thought "hey, I can do two things with one function! 
neat!"  It's a classic folly of software developers not considering the 
usability of what they are writing.  It is why you have people who aren't software engineers design or review UIs.

>>>>   Without strict properties, the author of the code cannot enforce 
> usage
>>>  semantics, and therefore, will lead to ambiguities.  The only exception 
> I can
>>>  see is calling a function with no arguments which returns void without 
> the
>>>  parentheses.  It cannot be mistaken for a property getter, because it 
> can't
>>>  be used as a getter.
>>> 
>>>  Could you please present an example of an ambiguity in the general 
> case? (i.e.
>>>  excluding assignment to const/immutable/(static pure) functions and the
>>>  delegate() foo(){})
>> 
>>  I mean semantic ambiguity, not compiler ambiguity.  I mean, the choice of 
> how the symbol can be used makes the symbol name ambiguous where it wouldn't 
> be if the usage was locked to one way or the other.
> 
> Sorry, I was implying examples of semantic ambiguity with my request.

OK, when you referred to the delegate thing, I thought you meant functional ambiguity.

Any term which could be confused as an action or a property.  For instance backup.  backup can be a noun ("do you have the backup?"), or it could be a verb ("did you backup the system?")

So if I have a backup function, and you use it as a property, what happens:


auto x = y.backup;

Is x now a backup copy of y, or is it a return value from some backup process?  Contrast that with the function style:

auto x = y.backup();

it definitely reads more like backup is doing something on y (like backing it up) and x is some sort of status.
 

>>>  TimeSpan.seconds(5); // looks ok to me, not great, but not misleading 
> either.It looks like a constructor, which it actually is.
> 
> This looks unnatural to me, both as a reviewer and as a coder. The reviewer 
> sorts the meaning quickly enough, after a little inference. But a coder will not 
> naturally write this the first time, assuming they haven't read the manual 
> recently.

As a constructor it looks unnatural?  How would you expect a constructor to look?

> 
>>>  TimeSpan.seconds = 5; // absolutely misleading.
> 
> And _looks_ absolutely natural ( therefore is absolutely misleading to both 
> coder and reviewer :) ). By the way, a 'bug' like this is a good 
> indication that the user wants a way to set a TimeSpan's span(?) outside of 
> the factory methods (i.e. an additional API feature).

The problem is, I can only "solve" this bug by changing the name of seconds to be more explicit, I can't disallow this code.

>>>  So I think even though it's somewhat of a combination of issues, 
> the
>>>  property issue is not invalid.
>>> 
>>>  The issue is more prevalent when talking about ambiguous words, 
> especially ones
>>>  that can be both nouns/adjectives and verbs.  The issue I have with not 
> being
>>>  able to require parentheses is, lack of parentheses evoke an 
> expectation of a
>>>  field, either setting or getting that field.  Parentheses evoke more of 
> an
>>>  action than a field, but that's not as strong, because you can 
> easily make a
>>>  function that is a property.
> 
> Yes, parentheses evoke actions more that data, and I would expect the average 
> coder to use them in a natural (for them) way. Generally, coders do not try to 
> make their code unnatural, except in sport. And differences in 'natural' 
> coding styles (i.e. ambiguities) are perfectly expected. To combat this (among 
> other things), the designer writes documentation. Therefore confusion and misuse 
> should only occur if the user a) hasn't fully read the docs or b) it has 
> been some time since they did read the docs, and they've forgotten pertinent 
> information. And if a user has forgotten what 'seconds' does, 
> they've probably also forgotten whether it's const, or immutable, or 
> pure or @property. Mandating parentheses doesn't help the user remember how 
> to call/use a function, because we Humans remember names extremely well, 
> purpose/behavior decently well and arbitrary tags poorly.

Again, the enforcement is for the reader of the code, not the writer.  
If you had no idea what TimeSpan.seconds(5) does, you would probably know what it means if you saw:

auto timeout = TimeSpan.seconds(5);

It's self-documenting.

> 
>>>  If you just require @properties to be called without parentheses, it 
> doesn't
>>>  solve the largest problem with D's property system -- that is, 
> being able to
>>>  omit parentheses for things that should clearly be viewed as actions.
> 
> :) If it's clearly an action, then shouldn't it have a nice actiony 
> name? :)

constructors usually don't have actiony names, they are named after the 
type they are constructing.  Factory methods are sort of a hybrid 
between actions and constructors, so I think it's ok to have nouns as 
factory method names.  But this is part of the design decision I should 
be able to make.  It should not be enforced on me to change the name 
because the language allows someone to misuse the library.

> 
>>>  Here is an artificial, but not so improbable example:
>>> 
>>>  stream.read = buf;
>>> 
>>>  what does this mean?  Does it mean, set the read buffer to buf?  Does 
> it mean
>>>  read buf into the stream?  I have no idea.
> 
> Really? I know it supposed to be a synthetic example, but read's a verb. It 
> does stuff. If it was the read buffer, it would be named readBuffer; a noun.

read (pronounced like 'red') is also an adjective, which can be a property:

book.read = true;

But even readBuffer could be an action (read the buffer) or a noun  (the read buffer) :)

>>>  But this is completely clear:
>>> 
>>>  stream.read(buf);
>>> 
>>>  it means, read the stream data into buf.
>>> 
>>>  However, D treats them both equivalently, and throws no error on the
>>>  super-confusing usage.
> 
> You are aware that the 'stream.read = buf;' is logically correct? And 
> that for whoever that wrote it that way, it had to be natural and non-confusing.

I wouldn't be so sure.  If I wrote that, thinking I was clever, and then went back to read it, I'd have to look stuff up again.  And then when I figured it out, I'd change it to the other style.

But in any case, it's the reader that I'm concerned about, not the 
writer.  The strict enforcement of properties helps the writer create 
maintainable code.  If you want to use a language that helps you write 
unmaintainable code, there's always perl :)

>>>  I understand that *most* people won't use it that
>>>  way, but as a library designer, I want to patch all the holes, and make 
> the API
>>>  as tight as possible.
> 
> But a hole isn't _always_ generated by 'unapproved' syntactic usage. 
> A hole only occurs when the syntactic usage causes the code to become 
> meaningless or invalid; and we can patch most (all?) of those.

The translation of the code into binary form is not what's at stake 
here, it's the human interpretation of it.  A good design takes both 
into account.

> 
>>>  I want code that uses the library to read as naturally as
>>>  possible.  So I might rename the function "readTo" to ensure 
> the verb
>>>  status of "read."  To me, this is a sucky compromise that 
> feels
>>>  artificially created by the compiler.
> 
> Improving the clarity of your library is a 'sucky compromise'?

If the library does not allow:

read = buffer;

then read is clear enough, because read(buffer) is clear.

The point is, the loose properties are forcing me to make something 
that's already clear in one context less clear in another context to discourage usage.  I 
want to make the user only call read using parentheses, I'd rather just 
have the compiler make them do it, not have to "hint" at it using a more
 verbose term.

-Steve