Programmer Tests as Agile Documentation talk at St. Louis OOSIG last night

I gave another talk on this subject last night at the St. Louis OOSIG meeting. Not a huge crowd, as the announcement came a little late (that’s my story and I’m sticking to it :)). Presentation went really well I thought, and I’m really getting my thoughts and ideas in focus around this subject. I do think there is a tool and a technique missing from my bag of tricks that would make life easier when using tests as docs.

There has got to be a way to navigate from a source method to the list of tests for that method. I believe that this map should be build by annotating the tests with the name(s) of the method(s) that it is exercising. And I believe that the documentation generators should build a map that lists all the methods of an application class as hotlinks. Choosing one of these hotlinks takes you to another page with a list of tests that go along with that method.

I think that would make life a lot easier when it came time to find out how to use a particular method.

Anyway, here is a link to the slides I used last night. As always, comments are appreciated.

— bab

5 thoughts to “Programmer Tests as Agile Documentation talk at St. Louis OOSIG last night”

  1. I like the test map idea. Also, the tests telling the "what" and not the "why" is a good point. I was talking about tests as documentation with some people the other night. One problem that was raised was related to tests telling the "what" and not the "why" with an example of tests for calculations. The tests may not describe the actual calculation. If it is a common calculation, people who have used it before might recognize it from the tests, but others might not. It might be hard for those who don’t recognize the calculation in the code from the patterns used in the test, so in that case even the "what" would be hard for some to realize.

  2. I think you’re on a roll. I can think of ways to build cross-references, using both static and dynamic (run time) analysis of the code. But attributes are a good, simple, cheap way to start. It’s the simplest thing that could possibly work.

    I think you’re on the right track.

  3. ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ??? ???? ???? ???? ???? ???? ?????? ?????? ???? ??? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ???? ??? ?????? ????

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.