“How to organize feature files?” was a question asked by Gojko Adzic in a recent blog. He presented several options and then asked for responses. The options included grouping them by user story, by capability and level of detail. This question has often come up over the past years in the workshops that I teach.
For a small set of files, you can keep them in a single directory and use descriptive names for the files. For a larger set, a directory hierarchy is a common organization. A network of files (using keywords to represent grouping) could also be created. Let’s look in detail at the hierarchy and network.
Work Hierarchy
The overall hierarchy structure could represent the work items or the functionality. With work items, the files are placed in a structure that parallels the sequence of when they are implemented. The iterations or development cycles are used for the folder names. This makes it easy to find the files associated with a story / work item.
Iteration 7 Story 171 Story 895
Functional Hierarchy
With functionality, the hierarchy represents the user experience or the operational workflow – the behavior at a higher levels. The folder names represent steps or sub-steps in the flow. There could be separate folders for operations which are in common to multiple steps.
Place an order Compute total order amount Compute tax No tax state Tax exempt organizations
At the lowest steps in the structure, there could be either a single feature file or multiple files in a folder that represents a behavior. This would be a small behavior that might have been created by a single story or by multiple stories.
An alternative is to use a network form, each file having metadata which could be used to group the files. For instance, tags could represent the groups. This would be useful if there was not an operational hierarchy. For example, feature files might contain:
@Order @Tax @Exempt Feature: Determine organizations that are exempt from taxes #........ @Order @Tax @NoTaxState Feature: Determine states for which no tax should be applied #............
The files would be displayed in groups based on the tags – either single or multiple. You could create multiple views of the same sets of files. Those views could also represent a functional hierarchy.
Suggestion
It doesn’t take too much effort to have files in a functional hierarchy. The advantage is that scenarios are now in the context of the flow. Scenarios related to the same flow step are together. A story that changes the behavior of an existing step may not create a new feature file, but just alter an existing one. The living documentation represents how a system is used, not how it was created. So it’s in the domain of the customer, not the implementer.
If a connection back to the stories is desired, you could use tags that identify the stories (e.g. @Story1234). Each feature file would have one or more tags to stories which were the reason for its creation or change.