[phobos] Time to get ready for the next release

[Robert Jacques]

On Tue, 26 Apr 2011 09:20:33 -0400, Steve Schveighoffer  
<schveiguy at yahoo.com> wrote:
> 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.

Ahem. If they are no different, then could you please name a word that has  
parenthesis as part of it? No?

Even capitalization is limited to a very limited set of by convention  
rules, beCause wE caN't reMemBer hOw To tYpe namEs liKe thiS.

>> 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 :)

The only time a corder writes confusing code is when your API confuses  
them. So not allowing 'confusing' code means the API doesn't have to be  
clear and meaningful, which is what I meant encouraging mediocre design.

And given that a coder doesn't ever try to write code that's confusing to  
them, whether or not it's confusing to you is a moot point, _unless_ at  
the same time the confusing way is a) invalid or meaningless and b) looks  
more valid than the non-confusing way.

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

You are aware that the counter argument is to regurgitate this argument  
back to you with a name change? that aside, design is almost always about  
compromise (though sometimes you get synthesis). And to find a good  
compromise you must explore the solution space. That a particular solution  
might be worse than any of it neighbors may occur (and I thank you for  
pointing out the flaws in this one), but that doesn't mean we shouldn't  
look.

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

Okay, first, I'm not sure you meant to imply this, but there are a host of  
other issues with enforcing @property, beyond the one we're discussing  
now, or even then ones mentioned in these threads.

Second, a large part of any design is nomenclature; bikesheds only occur  
when you've got a couple of reasonable, relatively equal solutions and  
multiple cooks/designers.

Third, 'not a real problem'? A) if we didn't think it was a 'real problem'  
we would not be discussing it. B) Please excuses the crassness, but that  
sounds suspiciously like 'my shit doesn't stink'

Forth, since you have asserted many times that parenthesis are part of the  
name, then isn't the problem with not-enforcing @property just that you  
don't want to name your functions clearly. 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?

*sigh* (Now would that be a triple sigh, a quadruple sigh or a double  
double sigh?) Anyways, no it's not impervious to attack. The discussion  
began as a discussion of _existence_ of issues with strict- at property. You  
counter-argued against the _importance_ of the issue. Now the _importance_  
of an issue is a valuable discussion, but responding with an _importance_  
argument to an _existence_ discussion without making a clear change of  
topic, is bad form.

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

A coder doesn't naturally try to write confusing/unreviewable code. And  
what you're thinking when you read it, is very similar to what you're  
thinking when you write it. Besides, greater expression capabilities allow  
you to express high level constructs better, which promotes clear,  
reviewable code.

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

Did you notice that you used two sentences in each example to explain it  
to me? With Method-as-Fields I only need to use one.

>>
>>>>  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?

No, I thought you were dismissing my opinion as not valid because it  
differed from yours. (I may have misunderstood, but you were very terse)

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

Yeah, I'm well aware of what happens when you let software engineers  
design your UIs. But your condescending tone isn't helpful to a level  
headed discussion and seems to speak to a general close-mindedness, which  
is also not helpful.

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

Well, since my experience with C taught be that status codes are evil, I'd  
never guess that. :) Anyways, since I'd never write y.backup() regardless,  
I can honestly say that I don't really see the difference anymore.  
Besides, the context and descriptive names for x and y are going to be an  
order of magnitude more important to clarity of meaning. i.e. status =  
db.backup; v.s. old_db = db.backup;

>>>>  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?

Capitalized, because types are capitalized and those are used to call the  
ctors.

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

And so long as the code is meaningful, why is disallow code inherently  
good?

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

But since this is the only correct way to use this function, by the time  
it gets to the reviewer shouldn't already be in this form?

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

Well, if you want to use ctor like names, then you should use a capital,  
otherwise it isn't a ctor like name, it's a field like name.

>>
>>>>  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 how often do you write something just to be clever? In production code?

> 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 would've thought that a code reviewer wouldn't want strict @property.  
That way the company can select their own, consistent style guide which  
everything is written in and reviewed in. Otherwise, every third party  
library embedded a different meaning into () and no-(), which makes code  
less maintainable, I would think.

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

But if the meaning is clear is one context and not in the other, wouldn't  
a reasonable coder never use the un-clear one?