Le 27/03/2015 15:02, CraigDillabaugh a écrit :
On Friday, 27 March 2015 at 10:10:37 UTC, Dominikus Dittes Scherkl wrote:
On Thursday, 26 March 2015 at 19:32:53 UTC, Idan Arye wrote:
But when it comes to heavily templated functions - understanding the
signature is HARD. It's hard enough for the top programmers that can
handle the complex D features - it's much harder for the average
programmers that could have easily used these functions if they could
just understand the documentation.
I think the documentation should simply contain the unittests - they
show quite well how to call the template, from minimal cases to the
complex ones.
Ok, they tend to show a lot of edge-cases, but even the very simplest
usages of a function should be unit-tested, so at least those have to
be part of the documentation.
Unittests are helpful, but I think examples aimed at demonstrating
usage are of more value if possible. Unittests and examples have
subtly different purposes. When writing a Unittest the programmer
will likely take whatever shortcuts they can to get data into the
tested function in the correct format, with the least amount of
code/effort legally possible. Whereas examples (hopefully) will try
to present inputs in 'real life' scenarios.
If the function inputs are trivial (ie. takes an integer or basic
string) then this isn't an issue. But for functions taking complex
inputs it can be a bit baffling for someone new to the language.
I must admit when I was new to phobos I struggled with the use of
unittests as examples, especially for functions taking
Anyway, unittests are better than nothing - if that is the other
option.
Just a little point :
I find some much examples not tested on Internet, so to me examples have
to by played by the compiler in the same time as unittest. Maybe it must
have a new keyword?
But that true unittest doesn't have exactly the same purpose and some
risk to be hard to read for a beginner.
