From: Colin Putney <colin@...>
Date: 2002-05-22T02:46:14+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

Here's my two bits.

I'm all for the idea of an automated tool for extracting the implicit 
documentation present in a unit test and making it explicit.

But I think we ought to be careful about the conventions we establish 
for making it possible. One of the things I like about Ruby is that it 
tends *not* to rely on conventions; most things are explicit. An example 
relevant to the subject at hand would be code organization. I can 
organize my code however I like: one class per file, multiple classes 
per file, multiple files per class, whatever makes sense for maximum 
clarity in that particular project.

I'd like to keep the same freedom in organizing test cases, particularly 
since "clarity" is in the mind of the comprehender, and can vary from 
project to project.

So my suggestion would be to establish a convention that explicitly 
states where the test cases for a given (part of a) class are, perhaps 
in a specially formatted comment.


Colin Putney
Whistler.com