www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Re: Example within documentations of D seriously need some improvement.

reply Jesse Phillips <jessekphillips+D gmail.com> writes:
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
May 27 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 5/27/2011 12:02 PM, 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).

I tend to prefer the unambiguous: assert(1+2==3); as opposed to the wordy and possibly misinterpreted: writeln(1+2); // should print 3
May 27 2011
next sibling parent Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 3:27 AM, Walter Bright wrote:
 On 5/27/2011 12:02 PM, Jesse Phillips wrote:
 Matthew Ong Wrote:


With all due respect for creating such a advance programming tool. How ever, there are plenty of rooms for improvement in helping new person to learn and adapt D.
 I tend to prefer the unambiguous:
 assert(1+2==3);

reader?
 as opposed to the wordy and possibly misinterpreted:
 writeln(1+2); // should print 3

Proper comment and proper output. writeln(1+2); // should print 3, numbers are added. How about string? No comment and No output. assert("abc"~"13"=="abc13"); People from Awk, C++, Java, ... read that totally different. Please consider mindfully. Please see my other post for more detail comment on the Book. Sucessful book publisher has done the detail research on how to communicate and draw attentions from reader. Do some simple survey with uni CP2 students and Year 1 working person. Properly done, it will be a good advantage for D Community pick up rate. -- Matthew Ong email: ongbp yahoo.com
May 28 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
 Proper comment and proper output.
 writeln(1+2); // should print 3, numbers are added.

There's nothing proper about that. I've already fixed a bunch of examples in the documentation because they had comments explaining the results instead of using an assert. And the comments were wrong, because it turns out that some part of the compiler has changed which makes the output of some call to writeln() different. You can only catch such cases if they're in an assert. Every new D programmer should learn about assert. Once they've seen a couple of examples there will be nothing ambiguous about seeing it in the documentation again. And you can't treat readers as if they're going to be newbies forever.
May 28 2011
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Sat, 28 May 2011 09:16:37 -0400, Andrej Mitrovic  
<andrej.mitrovich gmail.com> wrote:

 Proper comment and proper output.
 writeln(1+2); // should print 3, numbers are added.

There's nothing proper about that. I've already fixed a bunch of examples in the documentation because they had comments explaining the results instead of using an assert. And the comments were wrong, because it turns out that some part of the compiler has changed which makes the output of some call to writeln() different. You can only catch such cases if they're in an assert.

This is not really a reason -- examples are not compiled, unless you do it by hand. i.e. even if these were asserts, you still have to compile them to find the problems. A good reason, however, is that if you *do* hand-compile all the examples, finding the troublesome ones is much easier with assert (the same way unit test asserts are better than printing the results and comparing them manually). We can separate this out into two basic cases: examples you compile, and examples you read. In the latter case, either or writeln are just as informative. For example, code in print conveys its meaning just as effectively whether you "show" the result or assert the result. While reading, there's little way to prove the text is incorrect. In compilable cases however, I see advantages to both. In long examples, in which you want to know the thing works right, asserts are good. They are informative, they are robust, and any mistakes made in the code will show up very loudly. Writeln, however, has a distinct advantage over asserts -- it shows that something is happening. If you have a 100 line example, full of asserts, and as a new-to-D programmer, you run the code, it's a little "not-quite-convincing" when you just get a command prompt back. "Did I do something wrong? Is this code supposed to do something? Why don't I get any results?" There's a reason the quintessential example is to print a string. On the other hand, code that is full of asserts, with one printout at the end should be more than sufficient to give comfort that the thing is actually doing something, while using the advantages that asserts have. So I'd say every example that is *not* a unittest can have at least one writeln in it. The exception of course is unittest examples (which we may get some day). You don't want any printouts while running unit tests unless something goes wrong. I'd say all examples on D's web site should be treated like they are unit tests. For the very good reason that they *should* be unit tested. This is not a printed book or some beginner's guide, this is the spec, mistakes should not be ok.
 Every new D programmer should learn about assert. Once they've seen a
 couple of examples there will be nothing ambiguous about seeing it in
 the documentation again.

 And you can't treat readers as if they're going to be newbies forever.

If I were to write a new-to-D book, I'd use writeln exclusively for the first chapter to give them a sense of "OK, it works, I got it right". Then I'd introduce assert in a side-panel, and use asserts from then on, with printouts if needed. -Steve
May 31 2011
prev sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
 If you have a 100 line example

There's a few (I think?) of those in the docs. There was one such example for associative arrays which I've refactored a bit. And it does use writeln, as it should. The nice thing about that example is that it's at the end of the page, showcasing how hashes can be used, so it's kind of a wrap-up of everything learnt by the user who reads that page. Maybe we should have more of these types of examples for each topic. In those cases writeln makes a lot of sense. Hopefully actual examples will be autotested one day. Otherwise they can go out-of-date in-between releases. Btw, TDPL introduces assert as soon as page 10. And the book is quite assert-heavy overall, although writeln is used as well.
May 31 2011
prev sibling parent reply Matthew Ong <ongbp yahoo.com> writes:
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.


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 yahoo.com
May 28 2011
parent reply Jesse Phillips <jessekphillips+D gmail.com> writes:
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.
May 28 2011
parent Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 10:10 PM, Jesse Phillips wrote:
Hi,

That would be silly, I can't cover all of software development and I 

Great. I have seen publisher done that and those books are still on the shelf. Too heavy to carry around even with a back pack. :)
 D's unittests are not meant to replace a Unit test framework,

Unit Test framework. That is the case shown: http://www.digitalmars.com/d/2.0/unittest.html I was shocked to find only this. But DMD is just version 2.x so I gave some space in my assessment.
 Thank you for the feedback, I'll have to save your links for later 

Most welcome, thank you for listening also. -- Matthew Ong email: ongbp yahoo.com
Jun 03 2011