Example within documentations of D seriously need some improvement.

[Jesse Phillips]

Matthew Ong Wrote:

> 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.

Well, it is a possibility, but in this small attempt I've discovered that I suck at writing. I'll be working to make this complete, but it might be a very short book and it most certainly won't be perfect.

If by format you mean the presentation, they yes I have no clue how to use LatEx. And if you mean organization, well it is missing a lot but I think my use of code samples, output, and explanation is pretty standard.

 
>  >> 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.

Right, but I'm not claiming that it should.
 
> Yes. QA look for unit testing also. But they mostly just run to see if 
> the console output, with data in and data shown.

Yes, QA/everyone likes to see a scree full of green boxes, I do not know if this adds value other than "Hey look we did something!" not saying that isn't good. One thing I do think is silly is making the Unittest run before the program, generally you either want to run tests or you want to run the program.
 
> 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?

I think there have been some of these. D's unittests are not meant to replace a Unit test framework, they are meant to be used. A thing that you can put anywhere and throw asserts into lowers entry barrier greatly.
 
> 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.

I think bearophile's observation is pretty accurate. This will be an experiment. I'm interested to find out if D can be taught in a manner that best suites D, and if others find my style to be interesting.

> 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.

That would be silly, I can't cover all of software development and I wouldn't want to.

> 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?

If you aren't going to try for perfection you aren't going to get close.


Thank you for the feedback, I'll have to save your links for later review.