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.
