We're having difficulty reviewing https://github.com/dlang/DIPs/blob/master/DIPs/DIP1009.md. The value is there, but the informal and sometimes flowery prose affects the document negatively. There are some unsupported claims and detailed description is sketchy. We need a careful pass that replaces the unclear or imprecise statements with clear, straightforward scientific claims.

Can anyone help with this? For example, the first paragraph:

"D has already made a significant commitment to the theory of Contract Programming, by means of its existing in, out, and invariant constructs. But limitations remain to their usability, both in their syntax and in their implementation. This DIP addresses only the syntax aspect of those limitations, proposing a syntax which makes in, out, and invariant contracts much easier to read and write."

could be:

"The D language supports Contract Programming by means of its in, out, and invariant constructs. Their current syntactic form is unnecessarily verbose. This DIP proposes improvements to the contract syntax that makes them easier to read and write."

The change:

* eliminates the entire "implementation sucks" allegation which seems taken straight from a forum flamewar;

* replaces adjective-laden language with simple and precise statements;

* provides a brief factual overview of what follows.

Who wants to help?


Andrei

On Wednesday, 1 November 2017 at 22:04:10 UTC, Andrei Alexandrescu wrote:
> We're having difficulty reviewing https://github.com/dlang/DIPs/blob/master/DIPs/DIP1009.md. The value is there, but the informal and sometimes flowery prose affects the document negatively. There are some unsupported claims and detailed description is sketchy. We need a careful pass that replaces the unclear or imprecise statements with clear, straightforward scientific claims.
>
> Can anyone help with this? For example, the first paragraph:
>
> "D has already made a significant commitment to the theory of Contract Programming, by means of its existing in, out, and invariant constructs. But limitations remain to their usability, both in their syntax and in their implementation. This DIP addresses only the syntax aspect of those limitations, proposing a syntax which makes in, out, and invariant contracts much easier to read and write."
>
> could be:
>
> "The D language supports Contract Programming by means of its in, out, and invariant constructs. Their current syntactic form is unnecessarily verbose. This DIP proposes improvements to the contract syntax that makes them easier to read and write."
>
> The change:
>
> * eliminates the entire "implementation sucks" allegation which seems taken straight from a forum flamewar;
>
> * replaces adjective-laden language with simple and precise statements;
>
> * provides a brief factual overview of what follows.
>
> Who wants to help?
>
>
> Andrei

This actually makes the DIP slightly longer but hopefully makes it more clear.

https://github.com/dlang/DIPs/pull/95

I'm heading off to bed so I won't be able to respond right away to suggested changes.

On Wednesday, 1 November 2017 at 22:04:10 UTC, Andrei Alexandrescu wrote:
> There are some unsupported claims ....
> Andrei

Well, I'm struggling with the 'claims' on which the DIP mounts its argument.

(1) That the current syntax for contract programming limits its usability.

(2) That the more concise syntax being proposed, is both easier to read and write, and will therefore increase the usage of contract programming.

The problem with the DIP, as I see it, is:

The evidence for claim (1) is presumably points 1,2,3 in the Rationale. However, there is no convincing evidence to suggest there really is a connection between those points and that claim.

The evidence for claim (2) is??

Claims asserted as true without justification are just assumptions.

DIP authours would do well too study the Toulmin method of argumentation.

On Thu, Nov 02, 2017 at 03:40:17AM +0000, codephantom via Digitalmars-d wrote:
> On Wednesday, 1 November 2017 at 22:04:10 UTC, Andrei Alexandrescu wrote:
> > There are some unsupported claims ....

Sigh.  At the time of the review, I *did* mention that it needs to be clearer in its presentation and especially should include the rationale for the syntax as proposed.  However, the response I got was "it's not necessary, because it already references the previous versions of the DIP and therefore ought to be clear already".  Well, so much for that.


> Well, I'm struggling with the 'claims' on which the DIP mounts its argument.
> 
> (1) That the current syntax for contract programming limits its
> usability.

This could have been better worded.  It doesn't technically *limit* anything, but is more of a deterrent to using contracts because doing so with the current syntax brings quite a bit of verbosity to the code.

A lot of the arguments and reasonings happened on the forum review thread, which *should* have been included in summary form in the final version of the DIP.  But it didn't.  *sigh*


> (2) That the more concise syntax being proposed, is both easier to read and write, and will therefore increase the usage of contract programming.
[...]
> The evidence for claim (2) is??
> 
> Claims asserted as true without justification are just assumptions.
> 
> DIP authours would do well too study the Toulmin method of argumentation.

This is uncalled for.  This DIP did go through extensive review and discussion on the forum review threads, and actual code examples and syntax alternatives were put forth and argued for/against.  There was ample evidence in the form of testimonials from various D users about the verbosity of the current cumbersome syntax, and this DIP certainly was not the first time this issue was brought up.  Calling it mere "assumptions" is a bit heavy-handed, given the actual precedents.

It's not entirely your fault, though, since you probably were not here at the time, and wouldn't have been aware of said discussions.  This is why the DIP should have included all of those discussions (in summary form, of course), which is its only real fault here.  I did raise this issue, but it wasn't heeded to.  The argument at the time was that summarizing the discussions in the forum threads was unnecessary because, supposedly, Walter and Andrei would have already seen the discussions, and it was thought better to minimize the workload on their part by shortening the DIP.  Well, that didn't quite go so well, did it?

Now somebody will have to go through those review threads, summarize them, and add them to the DIP.


T

-- 
ASCII stupid question, getty stupid ANSI.

On Thursday, 2 November 2017 at 04:26:20 UTC, H. S. Teoh wrote:
> It's not entirely your fault, though, since you probably were not here at the time, and wouldn't have been aware of said discussions.

Yeah.. I had a brief look over some of those discussions before posting my comment above.

But even there I could not see a strong case being made.

This would be nice..convenient..and save a few key strokes is one thing...

..but we must go write a DIP because 'we need a change' is another all together.

The 'case of the stolen body'  ;-) ... seems to have been made solved though.. and 'do' seemed like a reasonable replacement.

but now we want free floating statements in D?

like:
----------------------
in(a > 0)
in(b >= 0, "b cannot be negative!")
out(r; r > 0, "return must be positive")
out(; a != 0)
--------------------

Now, I'm new to D (I only discovered it a month or so ago)...but do free floating statements already exist in the language?

If I saw that when I came to D a month or so ago, I'd would probably have moved on to something else...

On Thursday, 2 November 2017 at 08:58:03 UTC, codephantom wrote:

> but now we want free floating statements in D?
>
> like:
> ----------------------
> in(a > 0)
> in(b >= 0, "b cannot be negative!")
> out(r; r > 0, "return must be positive")
> out(; a != 0)
> --------------------
>
> Now, I'm new to D (I only discovered it a month or so ago)...but do free floating statements already exist in the language?
>
if() in template constraints are similar, so it is nothing shockingly out of character.
They are not free floating either as they are part of the function definition

int foo(int a) in(a >= 0)
do {
...whatever
}

vs

int foo(int a)
in {
   assert(a >= 0);
}
do {
...whatever
}

On Thursday, 2 November 2017 at 09:18:51 UTC, Patrick Schluter wrote:
> if() in template constraints are similar, so it is nothing shockingly out of character.
> They are not free floating either as they are part of the function definition
>

you know the old saying... what happens in vegas stays in vegas...

well... the same should be said for template programming.

what happens in templates, should stay in templates.

On Thursday, 2 November 2017 at 10:47:09 UTC, codephantom wrote:
> On Thursday, 2 November 2017 at 09:18:51 UTC, Patrick Schluter wrote:
>> if() in template constraints are similar, so it is nothing shockingly out of character.
>> They are not free floating either as they are part of the function definition
>>
>
> you know the old saying... what happens in vegas stays in vegas...
>
> well... the same should be said for template programming.
>
> what happens in templates, should stay in templates.

I disagree with that, because it would make the language very verbose.

On Thursday, 2 November 2017 at 08:58:03 UTC, codephantom wrote:
> Now, I'm new to D (I only discovered it a month or so ago)...but do free floating statements already exist in the language?

There's this one:

void main() {
    int i;
    switch (i)
        default: break;
}

you have 3 non-ambiguous and contiguous statements without a block: a switch, a default case (the "free-floating" one) and a break. Now why is this allowed is another story ;)

The whole combination makes sense just like :

function ...
in ...
out ...
do {}

would.

On Thursday, 2 November 2017 at 20:37:11 UTC, user1234 wrote:
> On Thursday, 2 November 2017 at 08:58:03 UTC, codephantom wrote:
replace function by void.