Coding with Confidence

I read and written many benefits of specs, from continuously testing to documentation. One benefit I experienced that never read about: having confidence in my code.

This wasn’t apparent at first, I realized this after a year working in an environment that took specs seriously.

At first I thought it was just me, but when I talked with my friend, Juan, about working in a spec environment, he echoed the same sentiment.

Once I had this coding with confidence feeling, I couldn’t go back to coding normally, even in my hobby projects.

Definition: coding with confidence

For me, having confidence in my code means:

Showing the work around my code to allow anyone, at anytime, to understand & modify the code in a project (also with confidence!)

I want to explain the difference in a typical project work flow with and without specs in: developing a new feature, finding bugs, and code reviews.

Developing new features

Writing a new software feature is one of the best parts of a programming job. The creativity, the challenge, the satisfaction. This is the work flow for two methods of creating a new feature: dive in & code, and spec driven.

I used to love the dive in and code style, especially on a greenfield project. Just implement code, little testing and be done. The immediate satisfaction is very high.

Now, I am all about the spec driven style, where specs come first, then code. On writing a new feature, writing specs before code feel less satisfying than ‘dive in and code’, but specs remain with the project after the feature is completed.

Ultimately, specs serve as a way to show the work being done with the code. What is being tested and how. Edge cases, exceptions, nil/null handling. Showing this work in spec is easier than in code as the spec spells out each case in a simple way (it 'returns false on nil inputs').

For anyone else to pick up the project, specs show exactly what is being tested and how. This gives confidence to new authors about how the code works and what is expected.

Finding Bugs

In contrast to building a new feature, finding bugs is one of the least favorite parts of programming.

SOLVING bugs is really satisfying, FINDING the bug is one of the hardest parts of programming and can cripple even the best programers.

Typically, all one has to use to find the bug is the code and the bug report (which can be of varying quality!) So the work flow is:

• Go into the code and see where bug may be
• Setup the reported configuration for bug
• Test if bug appears
  • Repeat until bug appears and is consistently replicable

Fixing bugs is a manager’s worst nightmare, not because it’s hard for programmers, but because finding the bug can take programmers an unforeseen amount of time!

Finding bugs with specs, is better. There is still code, the bug report, but because the whole spec suite is there to help, the amount of problem solving effort is reduced. The spec suite is one of the best tools to help find bugs! Now the bug hunt process is:

• Run specs:
  • if bug appears
    • find failing spec
    • repair bug
    • done
  • else bug does not appear:
    • (then the bug is a case which is not covered by specs)
    • create spec which replicates the same situation as the bug
    • repair bug
    • done

The bug hunt time with specs can be estimated with confidence. How? The amount of time to hunt for the bug can be estimated as the spec suite can indicate the scope of the bug, within known space or outside the known space. (Even if the bug exists outside the known space, specs help converge to the bug space very quickly.)

Afterwards fixing bugs with specs, one can be confident in the bug won’t appear in the project again. Why? The specs stay to demonstrate the bug scenario. (Just make sure there’s a comment to explain that spec is replicating a bug!)

Code reviews

I have seen code reviews become a fight between the author and the rest of the reviewers (or even between reviewers!) Code reviews can become one of the most stressful parts of working in a job with code. (It’s never easy to take criticism, even if it’s just code.)

With specs, code review changes completely. Specs show the work with exactly what is being done to everyone. Everyone can see what is being tested, how the code solves those problems. If there is a question about how something is done, a spec can show how.

To make code reviews smooth, write specs for the issue and make the code pass. With specs written as plain as day for everyone to see, the author can keep a cool head during review. Reviewers cover other items they find important to the code.

So before submitting code, just do a quick check:

• do specs cover new code?
• do specs cover known edge cases?
• all other specs pass?
• and anything else which the group feels is important. (i.e. code reuse, formatting, style, etc.)

As code author, having specs show the work of the code written makes code reviews a breeze. If the spec is there, that item is tested for. Reviewers see the spec and know it is covered.

When specs show all the required things for a code review, it’s hard not to beam with confidence.

Conclusion

Specs give confidence in code because they show the work being done by code, shorten bug hunting time, and gives new authors of the project confidence as well.

In code reviews, specs provide the author confidence in showing their work to everyone. Everyone can see what is being done and how.

In finding bugs, specs provide confidence in estimating time to hunt the bug down. Also, once solved, the bug won’t appear again because the spec will be part of the project to test for it in the future.

In creating new features with specs, there is confidence for any future author to know exactly what range of possibilities are there for the feature, how the code executes the feature, and how edge cases are handled.

Not only does specs give confidence to the current author, but to any future author that modifies the code.

To me, specs are a great tool to allow authors to code with confidence, and this is why I love to code with specs.