The Craftsman Toolbelt


This past couple of weeks I had the opportunity to pair with eight different craftsmen and craftswomen. We worked on very different codebases, from small startups to giant companies, on Scala, Ruby, JS, Clojure, Java… I learned a lot from each one of them.

I’ll try to sum it up in what I’ll call “the Craftsman Toolbelt”. Even though we were working on different environments, with different levels of information (some times we had the big picture, sometimes we had nothing), I saw many skills and disciplines at play when tackling the problem at hand.


The most evident discipline for me was TDD because there’s a lot of hype around it. When we were dealing with an unknown language, or library, or system, or all three combined, we could rely on TDD to ensure we’re doing what we mean to. This was an eye opener about the importance and utility of test-driven development.


  • Communicating through code

    Personally this is my favorite type of communication because it’s never out of date. Written documentation outside of the codebase can lie, people can lie, even comments can lie. The best way to know for sure what’s going on is to look at the code, and if it’s written with an audience in mind then you won’t have any troubles understanding it. Craftsmen know this and write their code considering future developers.

  • Written documentation outside of the codebase

    In reality, some programmers just won’t care for the next person reading their code and they’ll tackle the problem as quickly as possible, leaving a mess behind. This is were documentation comes in handy, instead of jumping around between incongruent functions across files and servers, you can expect that the documentation is somewhat up to date and use it as a resource to get a better general picture of what you can work with.

  • Communication with the client

    Sometimes the documentation and the code are working and they’re easy to understand, but they are solving the wrong problem. It’s important to talk with the client to make sure you’re on the same page. There are cheap ways to ensure you keep on the right track, such as weekly meetings, creating user stories, and defining acceptance criteria before you write any code.

  • Communicating about the project status and road map

    Sometimes after working on a problem for a while, we would find our estimates were off and there was no way we could finish as soon as we expected. The craftsmen I paired with did a fantastic job communicating with the client and the rest of the team, and managed their expectations accordingly. Solving a given problem will take time, how long depends on the elegance of the solution, a skilled craftsman will consider multiple options, their trade-offs, and do what works best for each client. Even when there are setbacks, honest communication can go a long way. This is why trust is essential in software business relationships, and we gain trust by consistently delivering what we say we will.


I don’t think this is a discipline but a quality instead, when we didn’t know much about the tools or the system, craftsmen were curious and explored what they had control over, to see what resources they had at their disposal and solve the problem.

It was a really great experience to pair with everyone and see how they think, what they value, and how they interpret and apply the principles of software craftmanship.