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 _______________________________________________ Zope3-dev mailing list Zope3firstname.lastname@example.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com