Tag Archives: Software Craftsmanship

There was a conversation around software quality over at the Software Craftsmanship slack team. It's an interesting subject but it often becomes confusing. Some of the questions that comes up are: What is software quality and how can we measure it? I'll try to add my twopence to the topic here, and perhaps make it slightly less confusing.

Lets start with a definition and then go from there. Oxfords English Dictionary has this to say on the subject:

The standard of something as measured against other things of a similar kind; the degree of excellence of something

To make sense of that definition we need to understand the context. What "something" is and what "other things of a similar kind" is.  To me this is pretty simple. The only person that can define what "something" is are the users of the software. In an enterprise system this is the enterprise user. In a API library it's the programmer using it. In the case of an end user application, such as a word processor or a game, it's the end user. And they will naturally measure this against other similar products or against their perception of how other similar things should work.

So my definition of software quality is:

The standard of said software as the end user of this software perceives it, measured against other similar software or the end users perception of how other similar software should work.

This makes my measure of quality rather narrow. I'm actually only interested in how my software is perceived by the users. This is also how I receive the measuring points needed to define what quality in my solution is. Therefor such tools as code analysers and test coverage is only important as long as the feedback from them helps me guarantee that the end user receives high quality.

So now what we are left with is understanding what the end user values as quality. As we start out, trying a new idea on the market, quality for the user may well be speed. It's certainly what we need to know if we should continue. To achieve this we create a PoC (Prof of Concept). This is often not a very well designed piece of software. It may well be something we will throw away a week after release. It's is as little as is possible to receive the feedback we need. If the users likes to use it we know it provided them with quality. Now we need to sustain and improve this quality.

As we continue to stabilise and improve our product we need to ensure that the user does not experience a regression in quality. Then they may well leave us for a competitor. To achieve this we need to ensure we have well tested and well crafted code. Here all the tools we can use to detect if our code is up to the high standard we need are of great help. Tools such as static code analysers, test coverage and so forth. Practices such as code reviews and pairing. The definition of quality is till the same however. Only the measures differs.

With this kind of definition I think it's easier to justify and measure what quality is. Keeping it this way makes it easier for all involved to relate to quality. And quality often comes up in conversations when we talk about the software we work with. Most commonly people try to refer to code quality and has a perception that well crafted clean code is what we always must strive for to achieve software quality. Clean code is important in many contexts. But not always. Sometimes speed is what we need. Short term speed and throw away code. It is, as always a matter of trade offs.


Legacy code is something we all have to deal with at one point or another. It's all around us. Even if we find it scary we have to learn how to handle it without being petrified in the process. This article will look at some techniques that I have used to tackle legacy code. It's a collection of things that have helped me go from feeling scared and apprehensive when working in legacy code to feeling challenged.

Before we dive in I'll start with defining what legacy code is. I've done so before on this blog. Since then I've learnt a much simpler and more precise way to describe it. Legacy code is all production code which makes you scared when you have to change it.

But what is production code? Production code is any code that provides the business with value. This includes, but is not limited to, code that executes in production, test code, automation code and any other code that helps the business do it's business.

So here we are then, with the legacy code. How can we go about doing this scary job without causing to much pain to the customer, who probably doesn't want to be disturbed at all? What should we think about? What patterns and tools would be helpful?

When the customer asks us to work on a legacy system we need to ask them why. Why does the customer want us to muck around in this old thing in the first place? What is the expected value of the change? Is it possible to deliver this value to the customer? Can we deliver this value in a better way? Can we get an of the shelf product and replace the legacy system with? Should we make a system rewrite instead? (this one should be approached with utter care)

The answers to these questions will not just question the need for change. It will also help guide you in your work. It will give you the indications you need to know how ambitious you should be. When you start on the path of reworking an application through slow, steady improvements rather then a big rewrite you will find that ambition level is important. It is what will guide you when you decide how much effort you should spend on improvements. What is the expected lifetime of the system you are working on?

Once you have the answers it's time to figure out where to start. The most obvious place to start is of cause where you stand. This is usually an approach that works when you know pretty well what needs to be done and where. If you are about to add a feature to an already existing part of a system or fix a well known issue then you should start where you stand.

When you are not quite sure where the problem is or when you need to find out where the real problem hot spots in your system are there is another tool that can be really useful. It is called Offender Profiling. The technique was create by Adam Tornhill and is presented in his book "Your code as a crime scene". He also has several talks (for example here) on the subject. Adam combines many years experience as a programmer with theories from forensic psychology. This have allowed him to think outside the box and be able to find patterns hidden in our version control system's (VCS) history data.

By using the history data from your VCS, combined with some very simple complexity metrics, this will allow you to find the most likely candidates for issues in your code base. The inspiration comes from a forensic technique called offender profiling.

Adam has in his book combined various other psychology concepts with VCS data which will help organisations make better use of their software. But that is for another time.

Now that we know where to start we have to understand what the code does. This is usually the biggest reason for fear in legacy code. That we don't quite understand how the code works. What does the requirements for this code look like. How do I know I haven't broken anything when I think I'm done? There are several different ways to attack this. We will look at four different patterns, starting with test.

First out is a way to mine requirements from executing code using tests. The tests are called Specification tests.They are pretty much the same thing as the tests we create when working with Behaviour Driven Development. What we aim to do is to understand how the system we are about to change should work by writing black box tests. To do so we use Gherkin's Given When Then syntax. We then run the tests on a running system. This whole process should ideally be fully automated and executable from the command line. But if that's not possible, just manually be able to run repeatable regression tests is a huge benefit. There are a couple of different frameworks to help with this. For Java and Ruby there is Cucumber, for .Net SpecFlow, JavaScript has Karma. There are many other frameworks available as well and for most other languages. You can also use tools like Selenium to execute your specification directly on the UI. Even if you are executing your tests directly against the graphical user interface and the cost of maintenance seems high this is a good investment. If this is an old application the UI will likely not change much. Also, you will get automated feedback on stuff the user will notice. If you can, sit down with users and watch how they use the UI. Then write the tests based on your observation.

With some test in place to make sure we don't have regression from the clients perspective it's time to start understanding the architecture and the code. We will look at two of Michael M. Feather's patterns from his book "Working effectively with legacy code" (WELC). We will also look at how we can use Simon Brown's C4 model for architecture to understand the architecture of an existing system.

The first of Michael Feathers patterns is Conversational Scrutiny (WELC p. 224). When you sit with an extra hairy bit of code like a long method or complex class, you often talk with one or more colleagues to get some help understanding it. The conversation that ensues is well worth paying attention to. It will often contain the abstractions that are missing from the code. The abstractions and the words that would have made the code easier to understand. The conversation in it self is of cause the key to understanding what the code does. But also make sure to listen carefully for the hidden abstractions required to make improvements. They tend to be embedded in the reoccurring words used during the conversation.

What is also important to remember is that a mess often asks for more messiness. Even a good team of developers have a scary tendency to keep adding messy code to messy sections of the code base. When scrutinising the conversation and noting the missing abstractions, don't forget to add them in the code. Don't forget to continuously improve the code.

The second of the patterns from Michael Feathers is Telling the Story of the System (WELC p. 216). This is a technique used to understand how submodules and modules work together. Each participant is responsible for telling the others the story of e's module. The story should be as brief as possible, preferably just a few words. It should also be told as if the audience knows nothing of the system.

By doing the exercise we become aware of what responsibility belongs where, as well as where it is currently located. It is a great way to understand how the system should be re-structured as well as how it currently hangs together.

Simon Brown, author of Software Architecture for Developers, have described a way to explain software architectures he calls the C4 model. This is a very powerful way to illustrate what a system architecture looks like. Used correctly on a legacy system it's almost embarrassing how bad most architectures are designed. The tldr; of it is that you have four types of diagrams. Each describes a model of the system. At the top level we have a Context diagram. This describes how the system fits into the rest of the world. One level down we have a Container diagram. This will show which "containers" the system is made up of. A containers is a deployable unit. This can be an IIS or JEE server, a database, a Docker Container or something else that is deployable. At the third level down we have the Component diagrams. They will describe the different components in some detail and how they interact with other components. At the bottom is the Class diagram. Class diagrams are sometimes very illustrative but often to detailed and can be left out.

The audience for C4 is mainly developers. The diagrams are there to help understand how the high level architecture is structured. When the model is true to the actual system it is also a very good place to start when looking to change the current architecture into something more fitting.

Now that we have, hopefully, understood how the system works, it's time to look at some patterns for how to make changes without fear. Or at least as fearless as we can be.

Let's start with a pattern from Martin Fowler's bliki called Preparatory Refactoring. This is a practice we should be doing all the time. Actually, the failure to do so is the main reason to why we have problematic legacy code in the first place. The basic idea is pretty simple. You have a new feature which does not fit into the code where it's supposed to. To make sure you don't create a mess when plugging it in you first refactor the existing code. You are done with the refactoring when the new feature fits in as if it had always been there. The effects is that the code is cleaner and more suitably structured to the requirements it is there to serve now.

When doing this in a legacy code base you end up adding loads of test. Remember, you can't do refactoring without covering tests, then it's not refactoring. Dan North and Michael Feathers came up with a name of this practice of adding tests to a legacy system in order to be able to change a part of it. They called it Light the Forest.

Imagine you have been asked to chop down a tree in the depths of a large dark forest. You have problems seeing your hand in front of you. The sensible thing to do is to light your way in, cutting a path and mounting torches, so that you can find your way back again.

When diving in to the depths of a legacy code base you are well advised to do the same. Lighting your way with tests. We call these tests assumption tests. They prove that assumptions we make on our journey are correct and stay correct.

As you work with your legacy code base and apply Light the forest over and over again you will start to see patterns in the forest. It's like seams starts to appear in the system. Along these seams you can start splitting the system up into components which are possible to test individually. Michael Feathers calls this the Seams Model. His definition of a seam is:

“A seam is a place where you can alter behaviour in your program without editing in that place.” (WELC p. 31)

The seams are places where you can inject tests, mocks, stubs and other things. It is also places where you can start breaking up the system into smaller more understandable pieces.

To break the system apart at the seams we use what is called Dependency Breaking Techniques. Michael Feather describes several in his book (WELC). Dependency breaking is often common refactorings made more difficult by the legacy code base. In statically typed languages such as Java and C# mocking frameworks can help allot when introducing tests and breaking dependencies. I don't generally use mocking frameworks when creating new code. But in legacy systems they can be a real life saver.

Another way to understand what happens when you want to break out a certain dependency is to pass in a null reference. The test harness will then quickly tell you if the specific parameter is used by throwing null pointers when the code under test tries to use the dependency.

If mocking or passing nulls doesn't work a possible way is subclassing. By subclassing a dependency, or some times even the SUT (System Under Test), you can stub away especially troublesome parts whilst using the real code in others. You can either create a specific test double or let the test class extend the dependency directly. This technique allows you to understand the SUT in a very intimate way. It will usually also make the code uglier. This is OK as long as it is done in a controlled manner and is removed as soon as possible.

Another thing that tends to be lacking in legacy systems is good names. Helpful names, providing good abstraction, is what make code changeable, flexible and ultimately non-legacy. It is one of the key aspects of a good code base. So when you work in a legacy system it is important to continuously find and add the missing names and abstractions to the code. As we know naming can be very hard. The conversational patterns presented earlier can be of great help in this work, as is the conversation that happens when pair programming.

Something Kent Beck said a couple of years back that helps allot when it come to names as well is: If you can't come up with a good name, then come up with a really bad one. A good name will come to you at some point in the future and the really bad name will poke you in the eye so you remember to replace it.

What good names tends to do in the long run is to help create good abstractions. This can be such a simple thing as extracting a class for an ID. If the ID is just a string or number it's hard to find where it's used. When extracted to a value object you are bound to find places where certain simple operations are preformed on the ID. Such as an equals operation. In some places there will be a null check, in others not. A common problem for bugs and a headache when changes are to be made. If ID instead becomes a class all this functionality finds a home. And all of a sudden ID's are not longer some random string in the system. It's a thing that we can reason about, not just on the whiteboard but also in code.

When you have found the names, and the classes or functions you want to create, you can use a number of common refactorings to extract them. Some are: Compose Method, Method as a Comment, Extract Method and Extract Class.

This article only scratches the surface of the subject legacy code. But I do hope it has tickled your curiosity enough to continue explore. A good place to start is the literature I've mentioned. Especially Michael Feathers and Adam Tornhill.

I would love to get your feedback, thoughts and ideas on the article and the subject in general. Did I miss something? Is there something that's not correct? Do you disagree? Or do you have furthers insights, thought and ideas you'd like to share? Please do post a comment.

The article is derived from a talk I do about tackling legacy code. If you are interested in this you are welcome to get in touch.


Legacy Code is important. Not just to us, as programmers, and the companies we happen to be working for. It has much larger implications then that. A couple of years ago I heard in a podcast that software has a 98% penetration rate on our everyday lives (I can unfortunately not find the reference now). The figure was for the northern hemisphere but the south is catching up fast. This means that our legacy as programmers, our legacy code, has an impact on pretty much every part of the society we live in. It affects us all every day of our lives. At home, at work, going in-between and pretty much everywhere else. I think we often forget this when we hack away at the task at hand. I certainly often do. We should take credit for all the great things we are able to create. But we also have to take responsibility for the bad. It is up to us to ensure that we create great software.

Because of this I think it's important to analyse how we deal with legacy code. Can we make sure that the code we leave behind does not become a burdon, a liability, but an asset? If we can, then how can we do this? And if we can't, then how can we ensure that cost is as low as possible?

Before I dig in to this subject I will try to define what I mean with legacy code. It's a term that is used by many and in many different contexts. Looking around online I find Wikipedias definition:

"Legacy code is source code that relates to a no-longer supported or manufactured operating system or other computer technology."

Another well known definition is Michael M. Feathers's from his book Working Effectively with Legacy Code:

"To me, legacy code is simply code without tests."

These two are in a way two ends of a spectra, where Wikipedias definition is rather weak compared to how we use the term in our profession and Feathers definition is rather harsh, considering that most programmers don't test drive there work and therefor create legacy as soon as they sit down at the keyboard.

There are a couple of other interesting pages on the subject that I have stepped over in my search for a good definition, one being the C2 wiki page, which I found the most inspirational, the other is /*Programmers*/ which discusses the subject in quite some detail.

My definition is:

Any part of a system, or whole system, that is hard or impossible to change when the requirements for it changes in such a way that the code needs changing to continue to serve it's users in the best possible way.

This means that code becomes legacy as soon as the context in which the code functions in changes and the code cannot keep up with the change in an easy way. What I mean with the context is anything that effects the code, this includes users requirements, regulations and the technical environment as well as anything else that affects the codes function. Easy to change is when the difficulty of change is proportionate to the perceived impact of the change. Some things are harder to change, for example a storage solution. Others are simpler, for example UI widgets or fields.

This makes all legacy code a bad legacy. That is how we use the term in our every day work. Therefor we also have to try to minimise the legacy code we create.

I have found two possible ways to deal with this. One is test first or TDD. The other is to ensure that each component, each function, is small enough and decoupled enough to be thrown away in it's entirety when it needs changing. I'll look closer at each in turn.

Test first or TDD is a way to work with the low level code as well as with higher level requirements by writing tests first. We have all heard the debate about this. I think this way of working is the only way to ensure that all aspects of importance in the code are tested in such a way that we can ensure no regression happens when we change them. This is, as far as I know, the only way that we can keep a system agile and easy to change. In other words the only way that we can keep a system from becoming legacy. Higher level tests are bound to requirements, lower level tests are bound to implementation on a class and method level.

What I have also found is that in such cases, sometimes when the tests are to hard to change to fit new requirements it is possible to throw them and the accompanying code away. The tests provides the documentation needed to improve the subsystem to work according to the new and old requirements. And the high level tests will catch functional regression. For this to work properly everyone has to realise that all code is design, every single line, and that everyone is responsible for the design.

I know that not everyone think they can do Test first. And perhaps it is not required as long as all requirements are covered in functional, BDD style, tests. In my experience as a Test first person this is not true but perhaps I fail on the more general level since I have the safety net further down and closer to the implementation.

The other way to avoid costly legacy is to make sure that each piece of legacy is so small that it is disposable when requirements change. I realised this quite recently when understanding Micro Service Architectures. The way I understand this is that the concept of a "class" is pretty much a service. Sure, the classes we normally create are much smaller but the higher level classes that we aggregate to provide a function of the system, the "public" interface, can be defines as a service. They are then bound together using a message or service buss instead of the normal object messaging used in classic class oriented systems. This means that it's an external orchestrator that provides the system of functions to the outside world. Tests are still essential and I believe they should be written first. But test in this context are functional tests which verifies the services functions as provided to the buss, and other services. Here BDD and similar methods are excellent. And the boundaries are made very clear. It also means that one service can be written in one language and another in another language. When a service needs to change it is quite possible to throw it away and create a new one. Chances are it's even better when reworked a second or third time.

The risk with this approach is of cause that the orchestration becomes so complex that the legacy is introduced on higher level instead. It is however often easier to mange complexity on higher levels then further down.

There are of cause situations when code does not have to be all squeaky clean. PoCs, pilots and other early incarnations of systems are often put together in a hurry and can often be thrown away as a learning experience. The problem with legacy arises when we risk loosing important functionality. So here it is our responsibility not to give in to pressure from others to let system with to much and badly controlled technical debt go live. This is not easy but I think we have to in order to build a reputation as professionals.

I hope to get your comments on the subject so please share your thoughts below or in your own blog with a ping back.

I had the pleasure to organise the first ever Øresund Software Craftsmanship Group Meeting on the 12th of September 2013. We were 14 attendees who met at Avega Group's office in Malmö. We opened with some beer and chit chat.

We then started the meeting with me presenting why I think this community is important and why I organised the meeting. Then we proceeded to the main topic of the night:

What is Software Craftsmanship?

We spent a good hour discussing this with the back drop of the manifest. The conversation was started with a question on if it is required to practice TDD to be a software craftsman. This was then quickly linked to the notion of well-crafted software and the conversation moved on to try and define this. Testing had a clear focus here.

The group then proceeded to talk about how to steadily add value to the customer through code. Upgrading infrastructure, language and tool versions and so forth and when this is a good decision, rather then a decision made by a developer who think new technology is cool.

After the break with pizza and beer we re-conveend to sum up and talk about what to do next.

It was decided that the group will move to FooCafe and we will meet the second Thursday of every month.

The following topics came up as possible for future meetings:

  • Tools and practices used to create well crafted code
  • What personal skills are required of a software craftsman
  • War Stories - tails from trying to implement SC in different contexts
  • TDD
  • BDD
  • Clean Code - Book and films
  • Clean Coder book
  • Study group about other books
  • Design Patterns Group
  • Interesting Speakers

For next meeting, the 10th of October, the subject will be:
Clean Code Episode 6 - TDD - Part 1
More info and registration at FooCafe