On 11/1/17 11:11 PM, Meta wrote:
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.
Thanks! We're still looking for sizeable improvements. Any volunteers,
please holler. -- Andrei
