Documenting method state of development

[Brian T Rice]

On Fri, 9 May 2003, Paul Dufresne wrote:

> Somehow, I feel like maybe I could be trying stuff, not yet ready to be
> tested.

Write up your changes in a local source file, and then run "cvs diff" on
it and post the output as a file to the list (or the whole file) if you
want some feedback on the choices before you commit.

> And this leads me to think about comments we could had inside, or in a
> separate file, about state of each method.

The state of each method? I'd say that any method with a good comment (one
without "TODO:" or "FIX:") is probably one to keep around.

> I have a bad habit of trying before thinking. And I like to avoid
> this for myself.

No, this is very often useful. Lee and I definitely have the opposite
tendency, and could use some balance.

> Just expressing some state that we could use, and give some code for:
> -english-like
> -translated to Slate, but not revised
> -semantically revised
> -syntactically revised (maybe, only after this, should the method be
> uncommented)
> -tested with at least a common case
> -tested with special cases
> -tested with a lot of data
> -used for 6 months
> -used for a long time

This is often what the CVS web interface is used for. You look at the
revision comments, see the colored diff viewer for the actual changes, and
judge based on that.

Your category definitions are nice, though, but it's difficult to make
something to handle that without a lot of work or an IDE.

> Does it seems a good idea?
> If yes, directly inside the code, or in a separate file?

Smalltalks generally do this pretty well, but they use chunk format with
bangs ("!" in fileouts) to annotate this. We really don't have room for
this until we have some Slate image that we can operate on separately from
Common Lisp. The primary focus for this in the tools are the changesets,
and we're not ready for that.

One thing we've considered is to have method categories (or interfaces)
set up using arrays in the source code whose elements are the method
definitions. E.g.:

packages Foo methodCategory: 'copyinging' containing:
{
x@(Foo traits) newFor: ...
[...].
x at ...
}.

Even so, we don't have Package objects yet. But our eventual goal is like
this, to handle it in the object-y manner.

-- 
Brian T. Rice
LOGOS Research and Development
http://tunes.org/~water/