Confident React App – Part 2

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.

One of the variations of Bootstrap’s list-group component

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!

Flattr this!

Confident React App – Part I

Kent C. Dodds has written one of the coolest pieces about software testing that I’ve read recently. It’s a great overview of the most common types of testing. The “CONFIDENCE you must have in the code you deliver” is an original light that he shines on the topic. Before you continue reading this, go read his article first. It’s well worth it!

OK, do you feel inspired too? Then let me explain and show you how I make my React codebases reliable and my confidence levels pretty high.

First step is to create our React app. I’ll use Create React App (CRA) since it’s super simple and still very popular.

npx create-react-app confident-react-app

Let’s start by fulfilling the base of Kent’s Testing Trophy requirements. For that we use a bunch of tools that will save us from most of trivial JS mistakes.

Linting

CRA uses ESLint by default which is great. From ESLint’s website: “JavaScript, being a dynamic and loosely-typed language, is especially prone to developer error. Without the benefit of a compilation process, JavaScript code is typically executed in order to find syntax or other errors. Linting tools like ESLint allow developers to discover problems with their JavaScript code without executing it.” And here’s the exact ESLint configuration used by CRA. You can see that the configuration also applies accessibility linting rules which is a really nice bonus. It helps us create code that respects some of the impaired internet users.

Static type checking

JS is a dynamic language and experienced developers can really take advantage of dynamic types and objects. But even experienced developers make silly mistakes, work with other less experienced devs and most of a JS codebase relies on static types anyway. So a codebase that uses a strong type system can benefit from detecting type error mistakes quite early. Facebook created and uses Flow, a static type checker for javascript.

OK, Flow is intrusive. In order to benefit from it, your code will look quite similar to TypeScript. To be honest, if you’re doing a small library/app and even working with other developers with limited experience, adopting Flow/TypeScript will probably not be worth it due to the added entropy. It’s a part of the nature of being a JS developer, you get burned many times until you finally learn and embrace. I personally got so used to it that most of the times I find super annoying to write so much type boilerplate.

Which one should you choose? That’s an ever going debate that I don’t know the answer to. I recommend that you try both and get the feeling for yourself. This kind of choice is just too hard to be impartial to take.

For this series of posts, lets assume we’re building an enterprise multi-national application in a team with dozens of developers spread across the globe. We’ll take Flow to the next level by using it in strict mode. From now on, every JS file must have // @flow in its first line, even tests.

yarn add flow-bin && yarn flow init

If you run the flow command it should report errors on the tests since it doesn’t recognize Jest’s global functions – itdescribe, etc. To fix this you must inform Flow that Jest is a library with all its interface definitions. Thankfully there’s flow-typed which is a tool for installing community-supported library interface definitions.

yarn add -D flow-typed && yarn run flow-typed install [email protected]

Unfortunately these tools do not run by default with CRA’s own scripts. Let’s validate our code for every action, so this how we setup the scripts in our package.json:

"scripts": {
    "start": "yarn validate && react-scripts start",
    "build": "yarn validate && react-scripts build",
    "test": "yarn validate && react-scripts test",
    "validate": "yarn lint && yarn flow",
    "lint": "eslint src/**/*.js",
    "flow": "flow",
    "flow-typed": "flow-typed"
  }

Phew! A lot of setup and we haven’t written any line of code yet. We deserve a break. Building up the confidence in your codebase is not so simple and can be hard to build – just like in real life – but the return on the investment will be worth it.

You can find the source code on Github.

Next post we’ll talk about what we’ll be building and how.

Cheers!

Flattr this!