On Sat, 28 May 2011 09:16:37 -0400, Andrej Mitrovic
<[email protected]> 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
