On Friday, 13 May 2016 at 20:39:56 UTC, Steven Schveighoffer
wrote:
Thoughts?
Yeah, I'm not a big fan of this either. A lot of in-comment
examples have been moved to unittests lately, and I think it is a
net negative:
* Running it gives silent output
* Data representation in source isn't always instructive
* Assert just kinda looks weird
The one pro would be that it is automatically tested... but is
it? Consider the following:
---
import std.stdio;
///
unittest {
writeln("Hello, world!");
}
---
That passes the test, but if the user copy/pasted the example, it
wouldn't actually compile because of the missing import.
Certainly, some surrounding boilerplate is expected much of the
time, but the unittest doesn't even prove it actually runs with
the same user-expected surrounding code. It just proves it runs
from the implementation module: it can use private imports,
private functions, and more.
So it is a dubious win for automatic testing too.
I prefer examples that you can copy/paste and get something
useful out of more than documented unittests. I actually really
like either one-liners showing the syntax and/or complete
programs that do something - MSDN is good about having those
kinds of examples.
D's documented unittests are somewhere in the middle... and I
think fails to capture the advantages of either extreme.
