Conventions Are a Silver Thread

Having a set of conventions around the format and naming of Use Cases on any non-trivial project is critical for ensuring a common understanding across the team and will greatly improve project organization and efficiency.

These conventions become a silver thread that can be used to trace a specific use case throughout the development process from the project management level down to the code level.

At Thunderbolt the following conventions have been used with great success in helping our team and clients deepen their understanding of a shared development process.

Actors

One of the first things that you should determine when wrapping your head around a new application is to determine the external actors that interact with your application. External actors are any individual using your application that can trigger a specific scenario like a Member who renews their membership.

We often come across systems that just have a single actor named User. Avoid calling any actor User. That is just too generic of a term. What type of user are they? Are all your customers drug addicts strung out from using your application?

It is better to separate users into specific roles that more accurately captures a use case scenario.

Most systems have at least three Actors: Visitor, Member, and Administrator

Having clear roles for the users of your application aids in defining preconditions that have to exist before the user takes on that specific role. If you have a Member role then it can be assumed that a Visitor has already gone through the necessary steps to become a Member, like signing up and activating their member account.

Defining specific roles will also help clarify the user experience for specific roles. Another benefit is that having multiple actors helps separate and organize large sets of use cases.

Take the time early on to think through the different actors that take part in your application, the analysis of your features will be easier and your final product will thank you.

Scenarios

Your actors interact with your application in certain ways, you should capture these scenarios as use cases following a certain convention.

A use case has two main parts: the summary which will be the name you enter into a feature story tracking application like Pivotal Tracker, Trello, or Sprintly; and the description which expands on the summary providing more context and detail.

Use Case Summaries

It is best to keep the summary of your use cases succinct and to the point by following the Actor Action format. Examples include:

• Visitor views frequently asked questions
• Visitor contacts us
• Member logs in
• Member edits blog comment
• Administrator creates a Member

We have seen use case summaries that read like paragraphs, they are impossible to review easily since the surface area on a feature tracking board is so large. Often each individual on a team will construct their Uses Cases in a different format resulting in a hodgepodge mess of stories. This creates stories that are harder to understand, organize and use, and can be impossible to track through the different layers of an application.

Use Case Descriptions

The use case description should follow a convention that expands on the summary providing more context. For the same reasons, it is important to follow a common convention across the team for the descriptions. Our preferred format is:

In order to provide some business value for the actor
As an Actor
I want to do a certain action

Which results in use cases like such:

In order to ensure members can change their password without customer service help
As a Member
I want to reset my password through email verification

People are often confused by the In order clause, the reason that is first and in the third person is to focus the use case on the business value that the scenerio provides. This helps to focus the use case on the business value it provides first and foremost.

Which would you rather review:

or

Feature Branching

How many times have you come onto a project and tried to make sense out of the current feature branches that are open? By naming a feature branch the same as the summary name of a use case it is easy to determine the current features being worked on.

$ git branch -c feature/visitor-throws-up

The id of the specific story that exists in your story tracking application of choice can be appended to the use case name to more tightly connect the branch to a use case.

$ git branch -c feature/visitor-throws-up-321293

Commit Messages

Commits should be identified by the use case they support. This helps to ensure that what you are committing is directly supporting a use case, and thus a feature. It also provides transparency to the team and the client.

Visitor eats a cookie [Progress]

- Introduce the Cookie model.
- Visitors can browse the site and eat a cookie because they are special.
- Add an integration spec to cover eating cookies.

Visitor eats a cookie [Finished]

- Add a burnt cookie state to the Cookie model.
- Refine integration spec to better cover the case when cookies are burnt.

A lot of story tracking applications like Pivotal Tracker support passing a change in state with the commit message that will be mirrored in Pivotal.

Visitor eats a cookie [Finished #321293]

- YadaYada
- YadaYada
- DoDahDo

For general commit message conventions follow the great and knowledgeable Tpope’s suggestions.

Integration Specs

Having strong conventions around your use case format can help to clearly organize your integration specs in your repository. For example, we naturally organize the integration specs by actor. This makes it easy to navigate through large amounts of integration features and the specific use case can be identified from the file name and directory structure.

spec/acceptance/administrator/adds_client.feature
spec/acceptance/administrator/logs_in.feature
spec/acceptance/client/activates_account.feature
spec/acceptance/client/logs_in.feature
spec/acceptance/client/views_invoice.feature
spec/acceptance/client/views_project_budget.feature

The features can also be grouped together if the subject of the scenario is repeated regularly.

spec/acceptance/client/invoices/submits_invoice.feature
spec/acceptance/client/invoices/edits_invoice.feature
spec/acceptance/client/invoices/views_invoice.feature

For any application of a decent size organizing your integration specs this way will bring much needed clarity and sanity. (Also, it’s assumed that you’re using Turnip for your integration specs, as it’s the only vegetably named integration library that matters.)

Model the Business

Consistency is key. It is important to use the same naming conventions that are captured in use cases throughout the application.

If a Company is known specifically as an Issuer then call your model an Issuer not a Company. Otherwise new developers, and you after not looking at the code for a few weeks, will have an additional cognitive load in understanding the system from the tension created between the reality of the business domain and what is captured in the code.

Often the name of models in a system become out of line with the business. If you change a role from Company to Issuer, take the 10 minutes it takes to rename everything.

Summarize

Let’s finish up by tracing a single use case through the layers of an application. An actor named Team Member has been identified that is a member on our team. This gives us use cases like:

Summary: Team Member logs in

In order to better support company transparency
As a Team Member
I want to login to access the team dashboard

…which then naturally roll into acceptance spec files like:

/specs/acceptance/team_member/logs_in.feature

…and a model like:

/models/team_member.rb

We have found that certain conventions work better than others, the most important part though is that you have some conventions in place to work from to help organize and increase a common understanding of a project.

Your conventions should be formed from experience and evolve out of a previous or existing development process. What you don’t want is an iron handed manager laying down a bunch of conventions that don’t make sense in the actual development process. If you follow your current conventions but let them evolve and be flexible, then you too will reach a state of development process bliss.