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
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
Zope3-dev mailing list