documented unit tests as examples

Adam D. Ruppe via Digitalmars-d digitalmars-d at puremagic.com
Fri May 13 14:16:04 PDT 2016


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.


More information about the Digitalmars-d mailing list