Phil'sown: Fusedoc Responsibility Ideas

Fusedoc Responsibility Ideas

1 Comment | Latest by: Nancy | Add Your Comment! »»

I like patterns. I'm a lot better at certain things when there is a structure to work within or a pattern or template to start from. Not everything is like this. Music in particular is one creative outlet where a structure helps, but often times in finding creative ways to deviate from the pattern.

I hardly ever use Fusedocs, and I would like to do so more frequently. One of the things I never liked about them was trying to figure out what to say in the Responsibility tag. The other items like Input/Output are simple and obvious, but it feels doubly redundant to type them in addition to code. On the other hand, the Responsibility tag has always intrigued me because they suggest typing it in first person, like this example from Hal Helms, 'I check the USER table for a match with the username and password sent to me.'

Beyond that I never know what to put, but last night (in the shower, of course, the nexus of all good ideas and cold water) it hit me. One of the concepts of Fusebox is to make your fuses as atomic as possible. Each fuse should do one thing, only one thing and do it very well. The responsibility of the Responsibility tag (yuk yuk) is to describe this one thing.

When I was starting out with Fusebox, I wrote fuses that did more than one thing. This made them far less reusable. I find more inexperienced developers doing this as did I when I was just beginning. The more I code (and live my life) the more I try to 'simplify, simplify, simplify!' Simple is elegant. Simple is the height of aesthetic. Simple is deliverable.

Enough foreplay; here's the pattern I've come up with for what to say in the Responsibility tag in four short sentences:

Say that the fuse does one thing: 'I do one thing.' Literally start with this phrase as a way of reminding yourself of this.

Say what that thing is in one sentence: 'I query the database for all recent blog entries.' 'I calculate the sales tax.' 'I take all the data from a record and load it into the session scope.' 'I display the main admin interface, with links to add, edit and delete items.' If you can't say it in one simple sentence, your fuse is trying to do too much.

Let me repeat that. If you can't say it in one simple sentence, your fuse is trying to do too much. (Simplify; simplify; simplify).

Say what the fuse returns, if anything. 'I return an array derived from the query result set.' 'I return true.' 'I return nothing.'

Say what the fuse does if it can't do that one simple thing. This can be more than one sentence if need be: 'If I can't connect to the database, I raise an error into the attributes.errors array. If I don't get any rows back, I don't raise an error.'

Finally, to keep your life fun and interesting, finish by having your fuse make a characterizing statement that is honest but positive. 'I'm a five minute hack, but I work.' 'I am simple and elegant.' 'I took 20 minutes longer to code than expected, but I was worth it!'

Here's a full example:

<fusedoc>
	<responsibility>
	I do one thing.
	I query the database for all recent blog entries.
	I return a result set.
	If I can't connect the database, I append an error to the attributes.errors array.
	If I don't get any rows back I return an empty result set.
	I am simple yet robust.
	</responsibility>
</fusedoc>

Jan 24, 2006 | coldfusion