This is the second post in the series where I show how I build up the confidence in the source code of my React apps. Please read the first post before continuing.
Communications is the key
A study of public GitHub issues found out that 78% of all software bugs are caused by specification error. Take a moment to let that sink in… That’s a big percentage! Basically, the quality of your team’s communication skills is by far the best investment you can do in order to reduce bugs in any application. The same research shows that type checking, either with Flow or TypeScript account only for ~15% of bug prevention.
So make sure your team/organization strive for creating and fostering a culture of safe and effective communication. People should communicate using a ubiquitous language which helps clarify specific jargons, contexts, and symbols. Not to mention that even improving formal language skills can have a positive impact. There’s nothing more powerful than a person who’s articulated and can think and speak.
Also the tools for communication should not be neglected. Wiki, Slack, whiteboards, Jira, Post-its, sharpies, company phones, video conference rooms and what-not are means to an important end.
Understanding the feature
We would like to quickly see the GitHub issues reported in our enterprise software in an integrated fashion so that we can find the necessary information fast; without switching context.
Our Customers
To achieve the desires of our customers, our (imaginary) multi-disciplinary development team has done research and a lot of discussions. Afterward, we came up with the following acceptance criteria written in our own syntax/DSL:
* Github integration *
When the user is in the issues screen
it must show a loading indicator while repo data is being fetched
and repo data is available
it must show a list of repos names
it must show a summary of all open issues
and there are open issues in a repo
it must show the count of opened issues next to the repo name
and when a repo is clicked
and it is NOT selected
it selects the clicked item
and there ARE open repo issues
it replaces the summary with the list of open repo issues
and there ARE NOT open repo issues
it shows the no issues message
and it IS selected
it deselects the clicked item
it replaces the list of open repo issues with the summary
The trick for reading the above is that indentation must be taken into account. All sentences are appended to its parent group. Sentences on the same level of indentation are not appended. The sentences usually start with setting some pre-conditions (e.g.: data is available) or user behavior (e.g.: clicking an item) and they finish with some sort of outcome/side effect. (e.g.: selects the clicked item).
Here’s a complete example:
When the user is in the issues screen and repo data is available and a repo is clicked and it is NOT selected it selects the clicked item.
It is a bit weird at first but our team likes it and it works for us. Gherkin is a very popular choice if you don’t want to roll your own DSL.
Component specification
Our designers opted for using Twitter Bootstrap as the base of the app GUI and for the feature we’ll need the List Group component. The component’s documentation serves as specs and acceptance criteria for the React implementation that we’ll provide.
So go back and read the acceptance criteria for the feature and the List Group specification. Try to imagine more use case scenarios or edge cases. Can you rewrite the sentences in a more clear way? Have you spoted an important missing thing?
In the next post we’ll dive into coding, I promise. But it will come with a twist.
Cheers!
