Version 2 (modified by Jonathan Lange, 11 years ago) (diff)


Review details

Document expectations

Intended user

Before someone begins using this document, I'd really really like it if they knew:

  • what a unit test is
  • how to write unit tests using xUnit
  • how to run Trial
  • how Deferreds work and how to use them


Once someone has read this document they should understand:

  • how to write tests for code that returns Deferreds
  • how to write tests for Twisted protocols (maybe)
  • how to use skip to write platform specific tests
  • how to use todo to write tests for non-existent/broken code

Document review

Have a look at wiki:DocumentationAnalysis/UserReviewTemplate for an alternative review style you might prefer.

Coverage of subject matter

Documents should demonstrate and recommend only best practice, except in clearly marked examples of bad code which leads to a justification of best practice. Any out-of-date or questionably intelligent ways of doing things shown in our documentation are problems. Best practice should be exhibited even when it makes examples longer.

Best practice includes: code doing what it puports to do; following Twisted coding style; using accepted idioms; and unless the documentation is to demonstrating a lower level feature by reimplementing a higher level one it should use appropriate library functions (eg LineReceiver) instead of doing a half-baked reimplementation. Further, code should be easily readable at the expense of lines of code -- code is more readable when the number of things it does per line is limited.

This document seems to cover the following subject matter at least acceptably well: list here

This document seems to be attempting to cover the following subject matter, but its coverage is flawed:

  • example 3 puports to demonstrate a webserver, but does not in fact run
  • section 2 says that the design of X solves Y problem when it actually doesn't
  • example 7 is using a sequence of functions to get Y result when we actually provide a convienience function Z

This document ought to be covering the following subject matter but is not:

  • the reason why Y is a better design than Z in this case
  • Foo useful library function
  • the X class of problems for which this approach needs to be modified

This document is recommending the following things that it shouldn't be recommending: [recall that merely mentioning something in a document often counts as a recommendation, and mentioning something only to denounce it is confusing and should be limited]:

  • X out-of-date library function
  • Y sequence of calls which have been superceded by Z library

This document could be supplemented by links to these existing pre-requisitie ("you should read this first") documents: list here

This document could be supplemented by links to these existing follow-up ("now that you know X you can try Y") documents: list here

This document could be supplemented by as-yet non-existant pre-requisite ("you should read this first") documents on: list here

This document could be supplemented by links to these as-yet non-existant follow-up ("now that you know X you can try Y") documents: list here


The following changes to the style of the document would make it easier to read:

  • shorter paragraphs in section 4
  • less hyperbole about the Twisted Way in the introduction

Overall summary

This document is: excellent / good, with some minor improvements to recommend / reasonable, with some pretty obvious improvements to make / better than having no documentation, but with some glaringly obvious improvements to make / so bad that it would be better to have no documentation on this