Why are homepage examples too complicated?

[cym13 via Digitalmars-d]

On Thursday, 13 October 2016 at 19:06:26 UTC, Karabuta wrote:
> I assume the purpose for those demonstrations are to win the 
> interest of the user as to how easy and clean D code can be. 
> Then why;
>
> // Round floating point numbers
> import std.algorithm, std.conv, std.functional,
>     std.math, std.regex, std.stdio;
>
> alias round = pipe!(to!real, std.math.round, to!string);
> static reFloatingPoint = ctRegex!`[0-9]+\.[0-9]+`;
>
> void main()
> {
>     // Replace anything that looks like a real
>     // number with the rounded equivalent.
>     stdin
>         .byLine
>         .map!(l => l.replaceAll!(c => c.hit.round)
>                                 (reFloatingPoint))
>         .each!writeln;
> }
>
> How is a new visitor supposed to know "!" is for templates and 
> not some complicated syntax?

You are definitely taking the problem in reverse here IMHO. The 
goal of such example isn't to get the user to get every little 
bit about it like “What does ! mean?”. It is impossible to 
explain each detail of the syntax in such a short format and that 
would only confuse the user to force everything in it anyway.

The goal of such example is for users to feel the general syntax 
when applied to an example expressive enough that they can follow 
it and infer for themselves the general meaning of the syntax.

The goal is to have them think

“Oh, that looks like a sequence of instructions on stdin.. byLine 
obviously mean that we read it by line, the map part isn't that 
easy to follow ok, but the last part each!writeln looks like 
we're writing each of a thing to a line... ok, so the actual 
replacement must happen in the map, yeah I see it, and there is 
the round part too so map must be some iterator thingy... Ok, I 
mostly get it.”

because if they do then it's where they get the confidence that 
they can red the language, that it feels "obvious" enough for 
them to use. That's what builds the idea of an intuitive 
language. Explaining how the code does what it does is definitely 
not the point here, knowing that ! is used for templates brings 
nothing. It could be used for any kind of other data structure 
the fact that “each!writeln” is understood as “write each line” 
is what really counts.

Maybe the example is poorly choosen and doesn't get new users to 
that point, but my experience showing it to friends is that it's 
definitely not that bad.