Thursday, October 28, 2010

Stories Before Bedtime

I find myself, yet again, forgetting my own advice & doing things in a manner that will give me unending nightmares in the long run.
Agile methodologies always talk in terms of stories. This works for software development when you incorporate non-technical people into a project. You allow them to answer the question "What is it meant to do?" - whether that's a single feature or the whole product - & their answer drives how it does it, how the deliverable is tested, & how success is measured (acceptance criteria).

Why do we forget these things as we go deeper into the development cycle?

Stories are good, in general, for all phases of the product life cycle, & indeed for all phases of business around product. If you can't clearly & succinctly state what the end goal is, or what the deliverable looks like, then failure is the most likely outcome.
That's reality.

Stories start with the big picture, but getting down to the nitty gritty, every component, every package, every class needs its own story. I get a little frustrated that I can't 'document' a package within the code, but that's why we have things like documentation in the first place.
Pictures are meaningless unless they have some words around them that say why things are represented as having certain relationships. Generating pictures from the code doesn't give you anything beyond what's in the code. If the code doesn't have a story in itself, then there is no story 'created' by generating pictures.

Each class should explain succinctly, then with more detail, what the purpose of that class is. That's why we have headers - not just for copyright or company policy - but to tell people what's going on. Tell your peers. Tell your audience - which is anyone who opens that class file.
Similarly, each method needs to have it explained clearly what the purpose is. It's not just the public methods, because that's all that the default javadoc setting generates - it's for every schmuck who follows you. It's for you in six months time when the droob you'd handed the code over to leaves the company suddenly.

Explain what the purpose is. Explain what the outcomes are. If you're not writing tests until afterwards (heaven forbid), then those tests will be meaningless unless they correlate with what the methods do, & therefore what needs to be tested.
Everything needs to be explained as if to newbie. Assume nothing. Start with the simplest possible statement & elaborate. Make references to other classes, packages, components, products - anything that might give the reader a clue as to what your thinking was when you used a HashMap instead of a TreeMap even if you know that the key is Comparable. There could be a valid reason, & it could be one of those things on which the operation of key features depends. If you don't tell the story, then no-one will know.

Stories should give you peace of mind. They should help you to sleep at night, knowing that you've done the best job that you can. Stories should come first, but they need to be in place before you can say that you've finished a project & you can put the whole deliverable to bed.

No comments:

Post a Comment