Brian Button - One Agile Coder

Updated outline for Agile Tests as Documentation

I've updated my outline a bit and fleshed it out some. This is the new outline, so please feel free to comment.

1. Introduction
   1. problem
   1. Documentation is an expensive anchor around a team's neck
   2. Lots of money to produce (40% on current project)
   3. Expensive to change (increases inertia and cost of change)
   4. Difficult to make comprehensive (need source anyways)
   2. Need something different that will promote minimal inertia, cost, and is accurate and comprehensive.
   3. Agile Developers write tests for code as it is developed
      1. Tests assert behavior of system (create invariant)
      2. Tests provide record of development stream (thought processes of developer)
      3. Tests change as code changes
   4. Can tests be used as documentation?
2. Who is our audience and what do they need?
   1. Application programmers -- users of our libraries
      1. Concerned with finding out what they want to know and getting back to work quickly.
      2. Concerned with most common usage scenarios most times, but still care about exception cases. Order of tests not important
   2. Maintenance programmers -- modifiers and extenders of our libraries
      1. Concerned with understanding underlying design and decisions
      2. Need guide through code. Order of tests important to them.
   3. Evaluators -- tire kickers
      1. Want to get moving quickly
      2. Less concerned with tests than sample code and quick starts
      3. Still want to understand architecture and design as part of evaluation, so will act as maintenance programmer in some ways.
3. My contention is that tests can do part of the job, but some text is still needed
4. Description of Caching design -- equivalent to short text and few UML diagrams
   1. Basic functions (add, remove, get, flush)
   2. Factories and equivalency of CacheManagers
   3. Background operations
   4. Liveliness of cache references (missing test???)
5. Components of a good test
   1. 3 A-s (Bill Wake)
      1. Arrange
      2. Act
      3. Assert
   2. Strong names for everything
      1. Test name tells what is being tested. Makes interesting tests easier to find
      2. Good variable names inside tests. Makes code easier to read
   3. Clear assertions. Defines purpose of test. Assertion should assert strongest thing that can be said about test. Should show thought into what underlying code does
   4. Suite name should tell reader what task fixture is testing/documenting
6. Test sufficiency -- do I tell the whole story with my tests
   1. Capturing design decisions
   2. Covering interesting use cases
   3. Showing error behavior
   4. Interactions with the environment
   5. Test organization for different audiences
      1. Application Programmers want to find common scenarios easily
      2. Maintenance Programmers want to follow original developer's train of thought
7. Conclusion: What prose and UML are needed to supplement these tests
8. Future directions in Tests as Documentation (Automation topics mostly)
9. Final question -- Did using tests as documentation save me anything?

posted on Wednesday, September 01, 2004 4:55 AM