Example within documentations of D seriously need some improvement.

[Matthew Ong]

On 5/28/2011 3:02 AM, Jesse Phillips wrote:
> Matthew Ong Wrote:
>
>> Perhaps format like coffee using more interesting side by side
>> comparison and with more writefln/writeln rather than assert.
>> Assert does not show anything visually.
>
> I understand this position and that new programers of D find it odd that examples don't have any output. However I have taking a liking to using assert as it documents what is expected and there is no need for a comment. On top of that it gets people familiar with assert and potentially using it in their own code and the icing is that unittests are built in the same manner (you should expect no output when everything is OK).
>
> In fact I have an introduction to programming book which uses just assert for most of the examples so far.
>
> http://nascent.freeshell.org/programming/D/LearningWithD.pdf

Hi

The I have seen partial format of your book. If you plan to sell it,
I am not too sure what in publishing direction and format you are heading.

 >> Assert does not show anything visually.
Perhaps some other asserts that can? I am sure it is not too difficult 
for someone to make assert with writefln functions instead of purely 
sprintf + assert? mixin could solve this easily.


Yes. QA look for unit testing also. But they mostly just run to see if 
the console output, with data in and data shown.

JUnit (Please see this, for D sake)
http://junit.sourceforge.net/javadoc/org/junit/Assert.html
BTW, is there something like JUnit API in D?


Comprehensive
http://www.wrox.com/WileyCDA/WroxTitle/Ivor-Horton-s-Beginning-Java-2-JDK-5-Edition.productCd-0764568744,descCd-tableOfContents.html
Can be used for referencing once, you are middle ranged. Not too good 
for CP1 or CP2. But CP3.

Jump Start Format
http://www.informit.com/store/product.aspx?isbn=0672329433
Easy self-learning with working example.

Example Format
http://oreilly.com/catalog/9781565923713
But other Oreilly, Lots of words, but little code. Yes, it is more 
towards the experts field market.

Well organised Book Publisher
http://www.packtpub.com/sites/default/files/sample_chapters/7726-ajax-and-php-sample-chapter-5-ajax-form-validation.pdf?utm_source=packtpub&utm_medium=free&utm_campaign=pdf
Best, learning by building working project sample.
Personally I like packtpub as their format help the reader to take note 
of important things. Even with a glace, you can pick up good stuff that 
works.

Suggestion is to find out what type of book format people browse more in 
a community library. I suspect it will be very different for asia, eu, 
usa, japan, taiwan, south american.

There is no book to cover it all in software development. Just book and 
good reading that show people how to get stuff on the visual. That is 
what get the client acceptance document signed and payment done for 
project.


I understand that D is trying to be correct 100% of the time. Not to pop 
that bubble, it is proven to be impossible from historical track record 
of mankind. Or else, why do we have unit testing/coding standards?



-- 
Matthew Ong
email: ongbp at yahoo.com