narrative testing and alphabetized code [04/16/2007 14:27:58]

For a while I was experimenting with mixing code, documentation, and tests all in the same file. The idea was that the reader could be presented with a logical series of steps taking them from knowing nothing about the code to understanding the finished design.

The idea is very much like literate programming, but instead of a static description of what's there and how it works, you get a linear story describing how things got to be that way.

I still think this is a good idea, but lately I've been separating things, so that the code goes in one file and the narrative file only contains the test cases and documentation. This seems to work well, at least for python: it means the docs and tests can be organizeb by use case (verb) while the code itself can be organized by class (noun). I suspect the original style is more suited for functional languages like haskell, where everything is grouped by verb - or even languages like C++ where methods can be defined separately from the class itself.

Anyway, this seems to clear up the code itself quite a bit, and makes it easier to use for quick reference, while the narrative becomes more of a tutorial.

If the code is to be a reference, then it ought to be organized cleanly. I like the way java forces you to put each (public) class in its own file, and I used that style myself for a long time. But I also like having one-file modules in python.

I've noticed that for myself, when I'm working with my own code, I have a really strong sense of where everything is. That is, if I'm working on one class, and I need to work on another class, I have it mapped out in my mind that the other class is either above or below me in the current file, or off "over there" in some other file. When I try to use other people's code, I usually don't have this sense of geography, and of course wind up feeling lost.

The implication for me as a user of other people's code is that I ought to read through and make a mental map of where each class or function is in whatever code I'm looking at.

The implication for me as a developer is that I ought to make it as easy as possible for other people to learn to navigate my code. With a decent IDE, it really shouldn't matter, but I notice my trusty emacs speedbar just presents classes in the order in which they appear in the code. It probably makes more sense to treat the code as a dictionary, and just organize classes and methods alphabetically. It's an arbitrary organizational scheme, but one pretty much everybody knows, and it's very easy to be consistent.

I don't know. I might change my mind later, but for today, I'm off to alphabetize my database abstraction layer.

update: d'oh! You can't alphabetize your classes if you use inheritance, unless your superclass just happens to come alphabetically before your subclass. Oh well.