Question

I’m working on a project and have developed the high level user requirements for what the system must do. This project is a php web application built on the CodeIgniter framework. Now I’m trying to take those requirements and break them down further into controllers/actions. What is the best way to do this?

I was thinking of creating a word document with a table that would have four columns. Column one would be the the name of the controller, column two would have the actions, column three would have the name of the view that is specific to the action, and the fourth column would show which users had access to that action. Does this sound like a good idea?

I like the interface first approach to building an application, but realistically, I need to know what views I need before I can create a prototype interface.

Could anyone help me out with how to plan the app and any documentation that might help?

Answer 1

Your breakdown is a good idea, but it’s really the second step.

here’s what I’d do:

• take your requirements, and turn them into a series of scenarios (“use cases”, “user stories”).

• Pick one, and sketch, like on paper, the basics of the user interface you’d want if you were to have the Good Code Fairy deliver the perfect system to you.

• separately go through the scenario, and underline all the nouns in the story; those are probably domain objects. Underline all the verbs in a different color. Each verb is a method of one of those domain objects. (In fact the domain object will be the object of the verb. Cool, huh?)

• Figure out how you would implement that user interface using those domain objects.

• Build it

• Show it to your customer, who will invariably say “I like it but“

• Put the changes and things you learned inot your requirements, and repeat until the check clears.

Peter Coad wrote what I still think is really the best beginners book on this: Java Design: Building Better Apps and Applets. It’s oriented to Java, but the design part is universal.

Your domain objects are the model, the display of your data is (roughly speaking) the view, and the code attached to actions is the controller.

---

On Use Cases

The “right way” to do use cases or user stories is subject to immense discussion and religious warfare. There are zillions of options, from Cockburn’s somewhat complex form, to notes scribbled on index cards.

For the kind of application you’re describing, I do two things: I try to keep them to 25 words or less, and I think about the SMART acronym.

• Twenty-five words or less helps keep them small. Doing a few small stories is preferable to spending weeks on a big one.

• SMART stands for “Specific, Measurable, Agreement with Responsibilities and Tests.” (Or at least that’s how I interpret it. There are other versions.)

  • Specific, you have to be comfortable you know what’s being asked.
  • Measurable, you have to have some way of testing or some kind of statement of what will be acceptable
  • Agreement, because it needs to be something you and the customer can both agree satisfies a need — in other words, the “meeting of minds” of a contract
  • with Responsibilities, you have to know what you’re being given, what the customer or user is responsible for providing, and what you are
  • and Tests, in other words, you should have an effective procedure that gives you the answer “it is acceptable” or “it’s not acceptable.”

The form I use has the pattern

User in a particular role
does something
resulting in some benefit

So, in your example, I would write

• Administrator (who?)
• lists all FAQs (does what?)
• to review them for updates. (why?)

The “resulting in some benefit” part is something I emphasize and a lot of other people don’t, or don’t even mention. It helps a lot later if you need to prioritize them.

The “test” part is a description of an acceptance test: you’re answering the question “Is this done?” So the acceptance test might be

• A logged in administrator selects “list FAQ”. All known FAQs are listed in correct format.

Ideally, you’d set this up so some tool, like expect or a gui test tool, can run this automatically, but especially in a small projects you may end up testing by hand. You want automated testing, because as you build the system, you want to do regression tests; that is, you want to repeat your tests to make sure nothing has been broken by a later change.