Example within documentations of D seriously need some improvement.

[Steven Schveighoffer]

On Sat, 28 May 2011 09:16:37 -0400, Andrej Mitrovic  
<andrej.mitrovich at gmail.com> wrote:

>> Proper comment and proper output.
>> writeln(1+2); // should print 3, numbers are added.
>
> There's nothing proper about that. I've already fixed a bunch of
> examples in the documentation because they had comments explaining the
> results instead of using an assert. And the comments were wrong,
> because it turns out that some part of the compiler has changed which
> makes the output of some call to writeln() different. You can only
> catch such cases if they're in an assert.

This is not really a reason -- examples are not compiled, unless you do it  
by hand.  i.e. even if these were asserts, you still have to compile them  
to find the problems.

A good reason, however, is that if you *do* hand-compile all the examples,  
finding the troublesome ones is much easier with assert (the same way unit  
test asserts are better than printing the results and comparing them  
manually).

We can separate this out into two basic cases: examples you compile, and  
examples you read.  In the latter case, either or writeln are just as  
informative.  For example, code in print conveys its meaning just as  
effectively whether you "show" the result or assert the result.  While  
reading, there's little way to prove the text is incorrect.

In compilable cases however, I see advantages to both.  In long examples,  
in which you want to know the thing works right, asserts are good.  They  
are informative, they are robust, and any mistakes made in the code will  
show up very loudly.

Writeln, however, has a distinct advantage over asserts -- it shows that  
something is happening.  If you have a 100 line example, full of asserts,  
and as a new-to-D programmer, you run the code, it's a little  
"not-quite-convincing" when you just get a command prompt back.  "Did I do  
something wrong?  Is this code supposed to do something?  Why don't I get  
any results?"  There's a reason the quintessential example is to print a  
string.

On the other hand, code that is full of asserts, with one printout at the  
end should be more than sufficient to give comfort that the thing is  
actually doing something, while using the advantages that asserts have.

So I'd say every example that is *not* a unittest can have at least one  
writeln in it.  The exception of course is unittest examples (which we may  
get some day).  You don't want any printouts while running unit tests  
unless something goes wrong.

I'd say all examples on D's web site should be treated like they are unit  
tests.  For the very good reason that they *should* be unit tested.  This  
is not a printed book or some beginner's guide, this is the spec, mistakes  
should not be ok.

> Every new D programmer should learn about assert. Once they've seen a
> couple of examples there will be nothing ambiguous about seeing it in
> the documentation again.
>
> And you can't treat readers as if they're going to be newbies forever.

If I were to write a new-to-D book, I'd use writeln exclusively for the  
first chapter to give them a sense of "OK, it works, I got it right".   
Then I'd introduce assert in a side-panel, and use asserts from then on,  
with printouts if needed.

-Steve