[Zope3-dev] Re: Windows eggs

[Stephan Richter]

On Saturday 14 July 2007 04:24, Marius Gedminas wrote:
> - API documentation: human readability is the primary concern, doctests
>     are in there just to make sure the documentation stays up to date.
>     These are .txt files.

I disagree. API reference should be automatically created. Text files are 
there to explain the API to someone who wants to use it. I write text files 
like I would write a lab report or a book on the subject.

>   - Short usage examples: sometimes it's simpler to show an example than
>     to describe the function in words:
>
>         def parse_date(date_string):
>             """Parses an ISO-8601 date.
>
>                 >>> parse_date('2007-07-14')
>                 datetime.date(2007, 7, 14)
>
>             """

I have not done this, because most interesting functions/methods are not that 
simple. Also, I really enjoy not having long documentation strings in the 
code anymore. That's a huge win coming from interfaces, in my opinion.

>   - Unit tests: there are many of those, they're independent (thus a
>     single .txt for a collection of tests is a Bad Idea), they're short
>     (so understanding and debugging is easy) and expressive.  I put
>     those into .py files full with functions that look like
>
>         def doctest_FooClass_does_this():
>             """Test that FooClass is able to ...
>
>                 >>> foo = FooClass()
>                 >>> results = foo.do_this()
>                 >>> for fruit, score, comments in results:
>                 ...     print fruit.ljust(10), '|', score.ljust(5), '|',
> comments Orange     | 9     | Tastes good, a bit sour
>                 Apple      | 8     | Varies
>
>             """

I never do this anymore. If I have a collection of utility functions, I Still 
put them in a text file, because text files allow me to concentrate on 
documentation. In you example above, for example, I miss a lot of explanatory 
text.  When I have utility functions that I want to explain independently, 
then I simply create one section/chapter per function. 

>   - Functional tests: these are .txt files that use zope.testbrowser and
>     are the hardest to debug.  There ought to be a better way to make
>     assertions about HTML output than using ELLIPSIS and then pulling
>     your hair out looking at huge and incomprehensible diffs.

I agree. You should give z3c.etestbrowser a try. It is based on lxml and 
supports XPath querying. I switched all my functional testing to etestbrowser 
now.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training