Documentation, more, more

goran.krampe at bluefish.se goran.krampe at bluefish.se
Tue Sep 2 09:40:19 UTC 2003


Hi all!

Just wanted to say that I wholeheartedly agree with Stephane and also
think that "externalized documentation" (that might be nicer to read
than code for some people) could also benefit from tests by being tied
to the tests in the manner I explained in the Magic Book discussion. A
short recap:

The idea was to simply link each "chapter" (or other granularity) of
documentation to one or more SUnit tests. The idea is that if the
documentation is focused on "black box use" (as it probably should be in
most cases) then it is highly likely that the documentation follows the
same lifecycle as the tests and NOT the same lifecycle as the code
itself.

So... whenever any of the linked unit tests either change or turn red
then the documentation also turns "red" meaning that it needs to be
checked again to make sure it is correct.

This means that the code can evolve as long as it doesn't change it's
"external contract". Like bugfixes or internal refactorings or whatever.
As long as the unit tests are the same and are green then the "external
contract" should also be the same and thus the documentation is still
valid.

Of course - adding more unit test methods could also signify something -
but now we are talking details... :-)

Anyway, I think it is a good idea but not sure yet how we can try it out
"for real".

regards, Göran



More information about the Squeak-dev mailing list