[TIP] Python Testing book review

[Kumar McMillan]

On Sat, Mar 6, 2010 at 1:25 PM, Tarek Ziadé <ziade.tarek at gmail.com> wrote:
> On Sat, Mar 6, 2010 at 7:55 PM, C. Titus Brown <ctb at msu.edu> wrote:
> [..]
>>>
>> I wrote some hacky little doctest-style code to make sure that the
>> basic examples in my book worked.  Highly recommended approach.
>
> It's not enough.
>
> I've done that with my latest book for most examples, but you cannot
> have a fully-covered book because some code snippets cannot be
> doctests. You would need to write test fixtures that would be longer
> than the book itself to have a good test coverage because a book is
> simply not an application.

Sphinx's doctest support is INGENIOUS.  If I ever had to write a book
(please, no!) then I would write it all in Sphinx.  For example, you
can do this in Sphinx:

.. doctest::
    :hide:

    >>> clear_something_from_last_example()
    >>> do_something_that_would_be_confusing_to_read()

.. doctest::

    >>> pertinent_example_code()

I highly recommend that everyone use this approach when publishing
doctested code.  It's just way too distracting to read setup/teardown
code when it only exists so that your code can be tested.  Example
code is crucial for explaining how things work and it's even more
crucial that it be concise and not contrived.

>
> Plus, in the process of writing a book, you have most of the time a
> tight schedule and the
> editor pressures you to return chapters on due dates, telling you that
> a bunch of reviewer will check
> everything on their side.
>
> At the end, when you get back all the reviews, and have a gut feeling
> that you need to do more reviews yourself, the editor tells you that
> it needs to be published asap, it's hard to tell him:
> "no, I don't want it published now, I want to have 2 months to review
> everything again".
> (and you are also really tempted to finish the project because its exhaustive.)
>
> The best editors out there won't do that: they will make sure the book
> is properly reviewed before its published, and "force" the authors to
> review and review again their work until its perfect.
>
> I've suffered from that and the latest book I've written was not
> enough reviewed imho, and could've been a much better book if I had
> more time to review or if I had better reviewers maybe. So I have a
> lot of empathy for the author of this book and I kinda agree with
> Jesse.
>
> Last, FWIW, I must admit that Packt does a much better work than any
> french editor I worked with, where there are *no* technical reviewers,
> or when they have one, it's someone who barely take a look at the code
> examples. The only techical reviewer I had on a french book was not
> familiar with Python :)
>
> My 2 cents, as an author of 3 books about Python
>
> http://www.amazon.com/Expert-Python-Programming-practices-distributing/dp/184719494X
> http://www.amazon.fr/Python-Petit-guide-lusage-d%C3%A9veloppeur/dp/2100508830
> http://www.amazon.fr/Programmation-Python-Tarek-Ziad%C3%A9/dp/2212116772
>
> --
> Tarek Ziadé | http://ziade.org
>
> _______________________________________________
> testing-in-python mailing list
> testing-in-python at lists.idyll.org
> http://lists.idyll.org/listinfo/testing-in-python
>