13 Tricks for Successful Side Projects

As I said last week, I released the v0.1 of Philou’s Planning Poker, my latest side project. Although I have a day job, a wife, a family and a mortgage to pay, I still manage to finish my side projects. In the past 7 years, I published 5 of these as open source projects, website, or wannabe businesses.

Side projects rely on 2 things : time and motivation. If motivation goes down, you’ll  stop working on it, and it will die. If you don’t manage to find enough time for it, it will also die.

Over the years, I accumulated best practices that increase the chances of success. Here is a shortlist of 13 of these.

A comic strip about side projects

1. Know your goal

As I said before, side projects are time constrained. If you try to follow many goals at once, you’ll spread too thin and won’t deliver anything. That will kill your motivation.

To avoid this, you need to decide on a unique goal for your project. It can be anything : learning a new tech, building a tool, sell a simple product, maintain a blog.

Depending on the nature of your goal, your side project can take different forms. 20 hours experiments are great for learning new techs. As a side note, MOOCs can also be very effective for this. If you want to start a business, start a lean startup concierge MVP. Finally, if you already know users who need a tool, build a minimalistic version for them.

2. Time box your work

Time boxing will force you to make the choices that will keep you going forward. The risk is to take on too many topics : more refactoring, more UI polish, more options, more bells and whistles. All these can be very interesting and valuable, but are usually not the main priority.

20 hours programs are time boxes, that’s one of the reasons they work. For other kinds of side projects, I do a quarterly prioritization. “This is what I’d like to have in 3 months”. I often slip a bit, but that’s not a problem as long as I stay focused on my goal.

3. Setup a routine

You’ll need to dedicate time to your side project. Think of what you could do if you worked one hour per day to it. 365 hours per year, or 90 hours per quarter ! That’s 2 full weeks of work !

In the long run, having a routine is more effective than anything else. After a few weeks of sticking to a routine, it will become part of your daily life, and won’t be an effort anymore. It will also help to forecast what you’ll be able to do in the coming month or so.

To setup a routine, block a slot in your day to work on your project, and stick to it. My own routine is waking up early to have some focused time. I have entrepreneur friends who did the same. GrassHopper founder says the same in this Indiehacker podcast.

4. Keep delivering to sustain motivation

Nothing kills motivation as not delivering. At work, I can go on without user feedback for a while (not too long though). Unfortunately, that does not work on a time constrained side project. We have only one life and we don’t want to spend our time on things that don’t matter. Things that don’t deliver don’t matter …

To get the technical aspect of delivery out of the picture once and for all, I use Continuous Delivery. Continuous Delivery is pretty easy to start with on a new project :

  • automate all your tests
  • setup a CI server
  • deploy when the CI passes

Once this is up and running, as long as I split my work in baby steps, I’ll be delivering.

The cover of the continuous delivery book

5. Use SasS tools

Setting up a CI and a deployment server can take some time. In 2017 though, online platforms make this very easy. Use as many as you can.

For Philou’s Planning Poker, I save my code on Github, test through Travis CI and deploy to Heroku. I also use Code Climate for static code analysis.

Most of these tools have some free plans for small or open source projects. That alone is a great advantage of making your project open source !

6. Pay for good tools

If you don’t want to make your project open source, consider paying for these services. How much you value your time will tell you whether to buy or not.

There are other things you should pay for as well. I definitely recommend paying for a good laptop and IDE.

Remember, anything that helps you to deliver also helps you to keep your motivation high. You have a day job that earns you money, so use it !

7. Pick a productive language 

Depending on your project, you’ll have a choice in which programming language to use.

Paul Graham advices to use dynamic languages. I tend to do the same, especially after watching “The Unreasonable Effectiveness of Dynamic Typing for Practical Programs”.

A presentation about dynamic typing

In the end, I guess it’s a matter of personal preference. Pick the language you’ll be the most productive with.

8. Use a popular platform

Use a popular open source platform to build your side project on. Useless to say, if your goal is to learn X, use X, even if it is not popular !

There are many advantages to using a popular platform :

  • you’ll have something that has already been production proofed
  • you’ll suffer less bugs (remember Linus’s Law “Given enough eyeballs, all bugs are shallow”)
  • you’ll get help from the community
  • you’ll find compatible libraries to solve some of your problems

The end goal is always the same : sustain your motivation by delivering fast enough !

9. Walk the edge

We don’t start side project to spend time updating dependencies. The saying goes “If it hurts, do it more often”. To save your productivity and motivation, always keep your dependencies up to date.

This is easy with automated test and continuous integration in place. I use no version constraint, but update all dependencies at least every week. I  commit if all tests pass. Sometimes I fall into small 5 to 10 minutes fixes, but that’s all it takes.

10. Take technical debt

When starting a new side project, you have no ideas how long it will last. Could be one week, for example if you started a 20h experiment at the beginning of holidays. Could also be 20 years, if you managed to transform this side project into a full fledged business.

Starting with all the practices that make large software systems manageable will fail. You won’t deliver fast enough. By now, you know the story, if you don’t deliver, you’ll lose your motivation.

I used TODO comments in my latest side project to keep track of the shortcut I took. I found it had 2 main advantages in my situation :

  • I had a quick view of how much total technical debt I took
  • if things get more serious, it will be easy to find improvement points

I know that TODO comments are controversial in the software community. In the context of new side projects though, they make a lot of sense.

My advice is to take technical debt !

11. Use your day job

I’m not saying to use time from your day job to work on your side project. That would be like stealing. Your day job can help your side project in many other ways.

One I already mentioned is using your income to buy better tools.

If you have Slack Time at your day job, you could use it to start a side project that benefits your company. You’ll need to make sure that this kind of arrangement does not pose any IP issues. It can result in a win-win situation.

Another way is to find subjects at work which will grow some skills that are also useful for your side project.

12. Talk about it

Talking about your side project serves many purposes :

  • it’s an unofficial engagement to work on it
  • it provides feedback
  • it could attract early users

To summarize, the more you’ll talk about it the more it will become ‘real’. You can share your side project anywhere : blog, Meetups, work, with friends or family. Depending on your topic, some places will work better than others.

Don’t be afraid that one might steal your idea. A side project is small, not yet rocket science. It’s usually too small to be on the radar of serious businesses, and too big for individuals.

Let me explain that. Very few people have the grit to turn their ideas into something real. If you encounter someone who has the grit and the interest, ask her to join forces !

13. Find real users

Deploying your software is nice, but it’s useless until you have users. Find some ! It’s never too early to find testers. If your first demo does not embarrass you, it was too late ! At the beginning, it can be as basic as walking through an unfinished feature to get feedback.

Real user feedback always results in both high motivation and value. There are many places to get beta users : at work, through friends … have the courage to ask !

That’s again a case for building your system in baby steps. The faster you get to something you can show, the faster you can have beta users.

Do it !

If I needed a 14th best practice it would be to start today ! As with most things, just do it !

Just Do It !

Side Projects Matter

As a manager, you could benefit a lot from helping your developers with their side projects.

I finished my latest side project. That’s the fifth serious one I bring to an end :

  1. 2010-2014 www.mes-courses.fr, an improved UI for online groceries. This was both a technical project and a wannabe business
  2. Since 2011, this blog
  3. 2015 www.agileavatars.com, a custom magnet shop for agile team boards. This was a lean startup style business project
  4. 2016 complexity-asserts a unit test matcher to enforce algorithm complexity. This was a technical project time boxed to 20h.
  5. 2016-2017 Philou’s Planning Poker, a technical product, that I built to solve my own problem.

The more I do side projects, the more I am certain of their value to my employer.

Hand drawing with stating 'creative business idea'

Reasons companies discourage side projects

Unfortunately, most companies discourage their employees to have side projects. It boils down to fundamental fears :

  • they might get less done
  • they might leave

While these are legitimate, most of the time, they are also unlikely or short sighted.

Why don’t they work extra hours ?

Said another way : if developers want to code, why don’t they add new features to the company’s products ?

From my own experience, having a side project has always been an energy booster. Side projects have made me more effective at work !

For a compulsive hacker, a side project is a hobby ! As painting, piano or soccer is to others. Working on smaller software, being in full control, renews the joy of programming.

They’ll quit once they’ve learned new skills !

Simply said, if a company’s retention strategy is to deprecate its developers … It’s got problems a lot worse than a few people doing side projects at night !

They won’t be as productive !

You could think that developers will be less focused on the company’s issues while at work. Indeed, passionate side-project hackers always have it on top of their heads.

Most of the time though, the extra energy provided by the side project out-weights this focus loss.

In the end, we should trust people to be professional. Let’s deal with the problem later, when someone actually starts to underdeliver.

They’ll leave if it turns into a successful product !

Building a product company is pretty damn hard. A time starved side project is pretty unlikely to turn into a successful business. Not much to worry about here ! If it happens, the company is lucky to have had such a productive employee.

They might steal our intellectual property !

This one is true. Only a very small minority of people might do that, but the risk remains.

You might conclude that it’s easier to play it safe and prohibit side projects … at the same time, it’s always sad to punish the majority for a minority’s bad behavior.

It boils down to a tradeoff between risks and rewards. How sensible the company is to IP theft vs the benefits of having a side-project friendly policy.

If you are wondering what these benefits are, read on !

Side projects made me a more valuable employee

As developers, side project teach us a lot. What is less obvious, is how these new skills benefit our employers !

Keep up with technology

A side project is an occasion to work on any subject, with any technology we want. That’s the perfect time to try that latest JS framework we cannot use at work.

This will help us and our companies to transition to these new technologies in the future.

Experimenting different platforms also widens our horizons. It teaches us new ways of addressing problems in our daily stack. For examples, learning LISP macros pushed me to use lambdas to create new control structures in Java, C++ or C#.

The conclusion is that side projects make people more productive and adaptive. Which in turn makes companies more productive and resilient

Understand what technical debt is

A technical debt iceberg

The bottleneck in a side project is always time. In this context, to deliver fast enough to keep my motivation high, I tend to take technical debt. Particularly because I ignore how long I’ll be maintaining this code.

Even so, if I later decide to stick to this side project, this technical debt will be an issue.

That’s what technical debt is : a conscious choice to cut a corner and fix it later. Without keeping track of the cut corners, it’s not debt anymore, but crappy code ! That’s why I ended up using #TODO comments in my side projects.

Later down the road, at any moment, I can decide to invest in refactoring some technical debt out. We can apply the exact same principles at our day jobs.

Understanding what a business is

Trying to make money from your side project taught me other kind of lessons. To sell my product or service, I had to learn a ton of other skills than the typical developer has. Nothing will sell without marketing or sales. I also had to dip my toes in design, web content creation and project management.

Once I went through this, I was able to better understand a big picture at work. It became easier to discuss with product, project and sales people. I’m able to make better tradeoffs between engineering, product and technical debt. Non technical colleagues appreciate that. As developers, it increases our value and trustworthiness.

Discover new ways of doing things

While progressing towards my own side project goals, I had to search the internet for help on some tasks. I ended up using SaaS tools, and discovered alternate practices to the ones I was using in my daily job.

That’s great for employers ! Developers will gain perspective about which company processes work well and which don’t. If you have some form of continuous improvement in place at work, they’ll suggest great ideas ! If you don’t, then you should start doing retrospectives now !

Companies should sponsor side projects

I hope I convinced you that side projects are at least as efficient as a formal training. The topics are unknown at the beginning, but that’s the trick : they deal with the unknown unknowns !

There are many ways a company can help its employees with their side projects :

  • Slack time is a great way to spark the interest in a topic. Developers might start something in their slack time, and continue as a side project. Provided the topic as value for the company, they could continue using their Slack time on it.
  • Hosting a Startup Weekend or a Hackathon. Most company offices are empty on Saturdays and Sundays. You could ask your company to lend its premises for such an event. It’s very likely that some employees will take part.
  • Even better, some companies, like Spotify, organize regular Hackathons on office hours ! That’s Slack time, on steroids !
  • Sponsoring internal communities can enable employees with side-projects to help each other. Sponsorship could be free lunch, premises or a regular small slice of time on work hours.
  • Providing a clear legal framework around side projects reduces the risks for everyone. Questions like the ownership of intellectual property are better dealt with upfront.

A photo of Spotify's open space during a Hackathon

If you are a developer looking for a side project idea, suggest slack time in retrospective ! You could also ask for sponsorship and organize a startup week-end or a lunch time community.

Finally, if your company is side-project friendly, communicate about it ! It’s a great selling point and it will attract great programmers.

Speed Up the TDD Feedback Loop With Better Assertion Messages

There is a rather widespread TDD practice to have a single assertion per test. The goal is to have faster feedback loop while coding. When a test fails, it can be for a single reason, making the diagnostic faster.

The same goes with the test names. When a test fails, a readable test name in the report simplifies the diagnostic. Some testing frameworks allow the use of plain strings as test names. In others, people use underscores#Multiple-word_identifiers) instead of CamelCase in test names.

RubyMine test report

A 4th step in TDD: Fail, Fail better, Pass, Refactor

First, make it fail

Everyone knows that Test Driven Development starts by making the test fail. Let me illustrate why.

A few years ago, I was working on a C# project. We were using TDD and NUnit. At some point, while working on a story, I forgot to make my latest test fail. I wrote some code to pass this test, I ran the tests, and they were green. When I was almost done, I tried to plug all the parts together, but nothing was working. I had to start the debugger to understand what was going wrong. At first, I could not understand why the exact thing I had unit tested earlier was now broken. After more investigation I discovered that I had forgotten to make my test public. NUnit only runs public tests …

If I had made sure my test was failing, I would have spotted straightaway that it was not ran.

Then make it fail … better !

I lived the same kind of story with wrong failures many times. The test fails, but for a bad reason. I move on to implement the code to fix it … but it still does not pass ! Only then do I check the error message and discover the real thing to fix. Again, it’s a transgression to baby steps and to the YAGNI principle. If the tests is small, that might not be too much of an issue. But it can be if the test is big, or if the real fix deprecates all the premature work.

Strive for explicit error message

The idea is to make sure to have good enough error messages before moving on to the “pass” step.

Cover of GOOSGT

There’s nothing groundbreaking about this practice. It’s not a step as explicit as the other 3 steps of TDD. The first place I read about this idea was in Growing Object Oriented Software Guided By Tests.

How to improve your messages

Readable code

Some test frameworks print out the failed assertion code to the test failure report. Others, especially in dynamic languages, use the assertion code itself to deduce an error message. If your test code is readable enough, your error messages might be as well !

For example, with Ruby RSpec testing framework :

it "must have an ending" do
  expect(Vote.new(team: @daltons)).to be_valid

Yield the following error :

expected #<Vote ...> to be valid, but got errors: Ending can't be blank

Pass in a message argument

Sometimes, readable code is not enough to provide good messages. All testing frameworks I know provide some way to pass in a custom error message. That’s often a cheap and straightforward way to clarify your test reports.

  it "should not render anything" do
    expect(response.code).to eq(HTTP::Status::OK.to_s),
                             "expected the post to succeed, but got http status #{response.code}"


expected the post to succeed, but got http status 204

Define your own matchers

The drawback with explicit error message is that they harm code readability. If this becomes too much of an issue, one last solution is the use of test matchers. A test matcher is a class encapsulating assertion code. The test framework provides a fluent api to bind a matcher with the actual and expected values. Almost all test framework support some flavor of these. If not, or if you want more, there are libraries that do :

  • AssertJ is a fluent assertion library for Java. You can easily extend it with your own assertions (ie. matchers)
  • NFluent is the same thing for .Net.

As an example, in a past side project, I defined an include_all rspec matcher that verifies that many elements are present in a collection. It can be used that way :

expect(items).to include_all(["Tomatoes", "Bananas", "Potatoes"])

It yields error messages like

["Bananas", "Potatoes"] are missing

A custom matcher is more work, but it provides both readable code and clean error messages.

Other good points of matchers

Like any of these 3 tactics, matchers provide better error messages. Explicit error messages, in turn, speed up the diagnostic on regression. In the end, faster diagnostic means easier maintenance.

But there’s more awesomness in custom test matchers !

Adaptive error messages

In a custom matcher, you have to write code to generate the error message. This means we can add logic there ! It’s an opportunity to build more detailed error messages.

This can be particularly useful when testing recursive (tree-like) structures. A few years ago, I wrote an rspec matcher library called xpath-specs. It checks html views for the presence of recursive XPath. Instead of printing

Could not find //table[@id="grades"]//span[text()='Joe'] in ...

It will print

Could find //table[@id="grades"] but not //table[@id="grades"]//span[text()='Joe'] in ...

(BTW, I’m still wondering if testing views this way is a good idea …)

Test code reuse

One of the purpose of custom test matchers is to be reusable. That’s a good place to factorize assertion code. It is both more readable and more organized than extracting an assertion method.

Better coverage

I noticed that custom matcher have a psychological effect on test coverage ! A matcher is a place to share assertion code. Adding thorough assertions seems legitimate, contrary to repeating them inline.

Avoids mocking

We often resort to mocks instead of side effect tests because it’s a lot shorter. A custom matcher encapsulates the assertion code. It makes it OK to use a few assertions to test for side effects, which is usually preferable to mocking.

For example, here is a matcher that checks that our remote service API received the correct calls, without doing any mocking.

RSpec::Matchers.define :have_received_order do |cart, credentials|
  match do |api|
    not api.nil? and
    api.login == credentials.email and
    api.password == credentials.password and
    cart.lines.all? do |cart_line|

  failure_message do |api|
    "expected #{api.inspect} to have received order #{cart.inspect} from #{credentials}"

Care about error messages

Providing good error messages is a small effort compared to unit testing in general. At the same time, it speeds up the feedback loop, both while coding and during later maintenance. Imagine how easier it would be to analyze and fix regressions if they all had clear error messages !

Spread the word ! Leave comments in code reviews, demo the practice to your pair buddy. Prepare a team coding dojo about custom assertion matchers. Discuss the issue in a retro !

'Just Do It' written on a board

20 Bad Excuses for Not Writing Unit Tests

I guess we always find excuses to keep on with our bad habits, don’t we ? Stephen King

  1. I don’t have the time. But you’ll have the time to fix the bugs …
  2. I don’t know how to write tests. No problem, anyone can learn.
  3. I’m sure the code is working now. The competent programmer is fully aware of the limited size of his own skull …
  4. This code is not testable. Learn or refactor.
  5. It’s (UI|DB) code, we don’t test it. Because it never crashes ?
  6. Because I need to refactor first … and I need tests to refactor ! Damn, you’ve fallen into the test deadlock !
  7. It’s multithreaded code, it’s impossible to test. Because it’s fully tederministic ?
  8. The QA department is already testing the code. Is that working well ?
  9. I should not test my own code, I’ll be biased. Start testing other people’s code right now then !
  10. I’m a programmer, not a tester. Professional programmers write tests.

A quote 'Be Stronger Than Your Excuses'

  1. I’m using a REPL, it replaces unit tests. Sure, and you’re running your REPL buffers on the CI ? and keeping your them for the next time someone modifies your code.
  2. My type system is strong enough to replace tests. Does it detect when you use ‘+’ instead of ‘*’ ?
  3. We don’t have the tooling to write unit tests. Get one.
  4. Tests aren’t run automatically anyway. Install a Continuous Integration Server.
  5. I’m domain expert developer, writing tests is not my job. Creating bugs isn’t either !
  6. We’d rather switch to the Blub language first ! You’re right, let’s do neither then !
  7. We don’t test legacy code. Specifically because it is legacy code.
  8. Adding tests for every production code we write is insane ! As shipping untested code is unprofessional.
  9. I find more issues doing manual testing. Exploratory Testing is a valuable testing, even more so on top of automated tests.
  10. Because my teammates don’t run them. Time for a retrospective.

'Just Do It' written on a board

From Apprentice to Master, How to Learn TDD (Test Driven Development)

I started to learn Test Driven Development a long time ago. Since then, even though I’m still not a master, it’s been my most useful programming skill, by far. TDD is the first trick every new programmer should learn. It made my whole career as a developer easier.

I’ve been working as a professional software engineer for more than 15 years, including around 10 years in the trading industry. Only once did I need to work on week ends or late into the night to fix emergency issues. I believe I largely owe this work-life balance to the high test coverage that TDD ensures by design.

TDD also enables safe refactoring. Refactoring enables incremental design which lets you decide late. Deciding late is how you make your customers happy by accepting late changes. Deciding late is how take up-front design easy, and improve your code as you go. Deciding late is how you build trustful and harmonious relationships with the stakeholders of your project.

Finally, writing tests before the code is both easier and more fun. Among compilation errors and never ending customer demands, the recurring green barre tastes like pure candy to the poor programmer !

A long winding road

The TDD Road

Here are the steps I took to learn TDD.

Learn the principles

The principles of Test Driven Development are fairly basic. 5 minutes is enough to know them forever :

  1. Write a failing test
  2. Make it pass by doing the simplest thing possible
  3. Refactor your code while keeping the tests passing
  4. Repeat until your acceptance test is green

TDD newbies might ask a few questions like :

  • Is making the code compile in step 1 or 2 ? Honestly, that does not matter. Write the test as if you had the code, then make it compile, make sure it fails, and continue.
  • How much should I refactor ? It often takes a good amount of experimentation to find your good balance. If you don’t refactor enough, you going to drown in dirty code. If you refactor too much, you’re going to waste your time (YAGNI). As a rule of thumb, Kent Beck’s rules on simple design are a very good starting point :

A visual graph of Kent Beck's rules of simple design

Find your tools

Back in 2003, after reading Martin Fowler’s Refactoring: Improving the Design of Existing Code book, I decided to give TDD a serious try. I was using C++ at work but we did not even have a nightly build. I had to download and setup CppUnit on my own. As solo endeavor, this was a required step to get into TDD.

Find and setup a tool. Which one should be rather obvious, if your team already uses a unit test framework, stick to it, otherwise, pick the most standard for your language, ex : JUnit for Java (you might as well start searching for a new job where they use a unit testing tool).

Train at a TDD coding dojo

Coding dojos were first invented as a tool to learn TDD. They were started by two french eXtreme Programmers Emmanuel Gaillot and Laurent Bossavit. It happens that I live in Paris, and that Emmanuel came to work as a contractor at the same company I was. I learned that he was organizing a weekly coding dojo open to any developer. That’s how I started attending coding dojos. Looking back, the TDD skills I learned at the coding dojo are just enormous !

If you are serious about learning TDD, attend coding dojos. Whether you find one in your city (ask meetup.com) or in your company does not really matter. If you cannot find any, just start one at work ! Send a public call for interested people (use wiki, mail, posters or whatever), book a room and start hacking ! Emily Bache’s Coding Dojo Handbook seems a very good reference about how to start a coding dojo (Disclaimer : I did not read the book, I only know it by reputation.)

Cover of The Coding Dojo Handbook

Use it

If you’re a professional programmer, you must be spending most of your time writing code. Take this opportunity to use TDD. You’ll be slowed down a bit at the beginning, but as both your code and your skills improve, you’ll get your time back manyfold.

I remember one of my first professional use of TDD was to write a small parser. A few weeks later I was asked to make it faster. Having tests around it made it easy to optimize it without breaking it.

Deliberate practice

In The first 20 hours, Josh Kaufman explains that deliberately practicing specific topics is a more time effective way of learning than simply crunching hours of practice.

My friend Thomas Pierrain is used to regularly practice short 30 minutes katas to sharpen his programming skills. Katas can be found at codingdojo.org, at cyber-dojo.org or in The Coding Dojo Handbook.


Meanwhile I was doing all this, I also spent a lot of time reading on the subject. At the time, there was a lot of things about TDD in the C2 Wiki, so I spent a lot of time there. Since then, I stumbled upon a few books that helped me to understand some aspects of TDD :

Cover of GOOSGT

Practice advanced topics

The TDD road goes on forever, testing has a lot of tricky topics. Once you’ve mastered the basics, it’s quite interesting to explore and practice more complex subjects. Here are a few things worth trying out :

  • Use automated IDE refactorings to keep the code compiling all the way through a kata
  • Do the same kata twice, using top-down and bottom-up styles
  • Do refactoring katas to learn how to work with legacy code
  • Do UI katas, to learn how to test the UI
  • Learn how to deal with DB
  • Learn how to handle remote services

If needed, invent your own katas to deliberately practice these topics and others.

The pitfalls

As any road worth walking, the TDD path is not linear and smooth. Before fully mastering TDD, you’ll regularly wonder if you’re on the right track. As any practice, TDD has pitfalls. I’ve fell into some quite a few times. I guess that’s part of the learning process.

Emerging Design

There’s always been a lot of misunderstanding around this topic.

Bad smells in your code make your tests harder to write. If adding a test is painful, that’s an indication that something could be improved in your design. It’s then up to you to know what. Once you’ve figured out what you want to change, use your existing tests to refactor your design first. Only then, add this new test.

As you can see, the tests will give you more feedback about the design of your code, but they won’t tell you what to do. That’s where your coding skills will help. This is particularly true about algorithms. Don’t expect a good algorithm to magically appear as you do the simplest-thing-that-could-possibly-work …

As with any rules, there are exceptions. At times, you’ll walk into a problem which emerging design is great. For example, I’ve done the Arab to Romans kata many times, and that repeatedly doing the simplest-thing-that-could-possibly-work yields a good solution.


Mocks are useful at times, but be careful not to overuse them. I already wrote about mocks. Too much mocking makes your test suite brittle, ineffective and difficult to maintain ! I’ve been bitten hard by this one on a personal side project, the day I decided to get rid of all the mocks, I shrank the test code size by 25%. Since then I learned about alternate techniques such as :

As an indicator, less than 5% of my tests use mocks.


In his keynote at RailsConf 2014 DHH explains the danger of testing metrics.

DHH's keynote at RailsConf 2014

By using TDD correctly, you should get a high code coverage as a side effect. If you get below 80%, you must be doing something wrong. The other metric you should keep an eye on is the total build time. Original eXtreme Programming had the 10 minutes build rule which states that if your build + tests takes more than 10 minutes, you should refactor it.

That’s it ! Things like 100% test coverage or test ratio are complete nonsense.

Pushing it even further

My promise, at the beginning of this post, was that Test Driven Development would make your life as a developer easier. Now let’s imagine that your whole team or company was using TDD. It’s a foundation on which to build a sustainable agile organization.

The mastery of automated testing at organization scale is a key element to continuous delivery, making releasing software a non-event, and as stress-free as possible.

Full adoption of TDD can yield to incremental architecture which delivers features faster, by skipping the conflictual arguments about supposed future needs.

Finally, TDD can simplify your processes and tooling. Team-wide TDD results in a steady flow of features on top of which it is easier to create simple and effective processes and tools.

The road is long, sinuous and at times rocky, but so are the rewards.

Most Scrum Teams Are Not Agile

Being agile is about adapting to change and continuously improving. I’ve seen (and been) in too many teams blindly following Scrum (Scrum Zombies) without figuring out how to continuous improve. The most obvious symptom is a boring (or no) retrospective.

Usually, it did not start that way, people had good intentions, and tried to follow the Scrum cookbook. Unfortunately, without any guidance or extreme perseverance, it is plain too easy to mess up the retrospective. If no concrete actions are scheduled at the end of the retro, if the same problems keep coming up at every retro, or if no problems at all are raised during the retro : your Scrum is somehow broken !

One of the promises of Scrum is to keep code quality high, in order to be able to adapt to late changes. Without a good retro to update the coding standards, the working agreements, or to spot and organize large scale refactoring, this will not happen.

One of the agile principle explicitly states the need for motivated team members. In Drive Daniel Pink explains that one of the ingredient for motivation is autonomy. As a way to fix recurring problems, effective retrospectives will create autonomy, and enable motivation. Dysfunctional retros will slowly kill both …

Although continuous improvement at all levels is one of the most important element in your process, it needs a bit of practice to setup right. After trying different approach in different teams, I compiled a list of the things that worked for me :

The cover of the Daniel Pink's "Drive" book

How to do successful retrospectives

Start !

Sounds obvious ! The first step is to schedule a recurring meeting and invite all the team. Someone should take care of facilitating. If you want to improve things, do this yourself at the beginning ! Once the practice is in place and everyone sees the benefits, you’ll be able to get some help.

Here is a crash-course about how to organize and drive your first retrospective. If your team is distributed, you’ll need a slightly different setup. In my previous team, we had success using Trello, you can read more about it here.

Just Do It picture

Make sure everyone talks

Retros should not be “just-another-boring-meeting” ! People should be excited to be there and to solve their recurring problems. I’ve seen retros where no one would speak, as if there was absolutely nothing to improve ! I’ve also been in retros where people raised collaboration issues, and came up with drastic improvements to the way they work, like adopting pair-programming for example.

There can be many reason why people don’t speak : habit, organizational culture … Whatever the cause, if you show them the path, if you demonstrate that retro work and that it is safe to speak, you’ll get them to participate.

Here are a few tricks to guide a team there :

  • It is said that if someone does not speak in the first 5 minutes of a meeting, he’ll remain silent for the rest. That’s why energizers work. They force everyone to participate to a Fun activity right from the start. Fun Retrospective contains a lot of engaging energizers.
  • Bring food ! Having food at work was one of Kent Beck’s main advises in eXtreme Programming, Embrace Change. Food is social and create a more relaxed and safer atmosphere.
  • Before you start the meeting, it might be useful to repeat the Retrospective’s Prime Directive.

Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.

  • As the animator, you should make sure the discussions don’t degenerate into some kind of trolling or blaming. If it’s the case, remind that this is not the way the retro is meant to work. In worst case, give a 5 minutes break to everyone to calm down.
  • If needed, have a private discussion with people outside the retro to make sure that they understand the “Blame the process, not the people” principle of the retro well enough.

Dealing with “bad” behavior in retros is a wide topic which I am only scratching the surface here. I guess I could write a full post about it.

The cover of the "Fun Retrospectives" book

Get out of with actionable tasks

If you want a sure way to screw up your retros here it is : end the first one with no actionable things to do ! People will learn that it’s a useless pscho-blabla meeting for agile softies.

This should be the absolute priority during the first retros. There are various kind of actionable tasks. Teams can adopt new conventions, decide to tackle some specific refactoring, or build a small new tool …

Actionable items should be small enough to be completed in one sprint. This is fine for refactoring a class, adding a SonarQube rule or asking for something from another team. What about larger tasks ? Suppose you just identified a large refactoring to do, how do you get started ? I know 2 strategies for that :

  • Only identify the first step of what you want to start. At least, that’s enough to get started and learn what to do later.
  • Agree on a Mikado discovery task to understand what needs to be done. Code is not the only thing that can be refactored with the Mikado method ! People have used it to transform organizations !

It’s also a good habit to book the rooms for extra time after the official retro time. Nothing is as frustrating as being interrupted while investigating a promising improvement !

Finally, I think it’s a good practice to review what happened of the improvements that were selected during last retro. It stresses the importance of doing what was scheduled in retrospective. It also gives a chance to investigate the reason why they were not done !

The cover of the "Mikado Method" book

Put them in the sprint

When actions are selected in the retro, you should add them to the coming sprint before it starts. Obviously, you’ll add non business related items in your sprint backlog. Whatever you might have hear from agile zealots, do it ! Process improvements are fist class backlog citizens, just don’t discuss them with your product owner.

If you want a chance to deliver what you committed to in your sprint backlog, you’ll need bandwidth for that ! They are many ways to do get that. Some teams use slack time, others reserve an ‘improvement day’ every sprint. My personal favorite (and the one we’ve been doing at work) is to estimate the improvements in story points and reserve a fraction (ex 20%) of your story points for improvements.

You can try to negotiate your improvement ratio with your product owner … or you might also just set it yourself ! The team is responsible for the quality of its work. Better be sorry than ineffective. If you stick to your ratio and only work on the most important improvements, it’s usually pretty easy to justify working on them. Plus if you manage to go under the radar for a few sprints, the results of the improvements should speak by themselves.

Do them as soon as the sprint starts

One last thing. Start to work on your improvements as soon as the sprint starts.

Improvements are similar to investments : you invest in process, tools or code in exchange for more value creation downstream. Once you’ve decided to invest in something, what’s the point of waiting 1 week ? Plus if you wait for later in the sprint, you run the risk of having unfinished improvements at the next retro, which might interfere when prioritizing new ones.

Continuously improving teams

Being part of a continuously improving team is easier to live than to describe. It feels like the future is bright. Once a team has mastered continuous improvement, people can be optimistic that they’ll manage to adapt to change later down the road :

  • They could switch gears and go full speed on a particular re-architecture
  • They could change their working agreements to adapt to new constraints
  • They could re-focus their efforts to handle a maintenance pike

At the end of the day, bottom-up continuous improvement makes everyone’s lives easier. Developers experience more autonomy while improving their productivity, they can do good work (which also means spending less time bug-fixing). Product owners learn that they can trust the team to do their best. Sponsors get more value for their money.

Agile teams bend so they don’t break !

A Straightforward Way to Scale to More Than 1 Scrum Team

How come the “agile scaling” landscape seems so daunting and bloated ?

Being agile should be about taking baby steps, doing things incrementally, starting with the simplest thing that could possibly work, slowly but continuously improving and trying out experiments.

Here’s a real-life 2 hours change that kicks-off a very efficient organization for a few scrum teams.

A guy jumping from a cliff into the sea

“SafeLess” : everything will go fine as long as you follow the principles

A classic story

Without doing anything about it, there are a lot of situations in where Scrum teams will collaborate inefficiently. For example if you are a developer within a medium or large company, suffering from communication loss between your team and others. Or you could be the owner of a software startup, needing to dramatically grow your dev team.

Whatever your situation, without good collaboration, the output of two Scrum teams is bound to be a fraction of the sum of their individual outputs.

Our own situation

We are a group of 4 teams that spun out of the R&D division. We are working to build a highly reusable component for the future versions of Murex’s main product.

While in R&D, teams were aligned with technologies. Now shifting to a product focus, this layered team structure makes it hard for us to organize efficiently. To make things even more tricky, the component we are building is something huge by itself, and we really need to find a way to deliver it incrementally.

This tech-oriented, low synchronization organization of team backlog was really underdelivering. It was not rare to see stories jump from one team to another, as dependencies were discovered, taking one full sprint every time. Integrating end to end features often took a few sprints instead of a few hours …

Clearly, we needed to do something.

The simplest things that could possibly work

Hopefully, all teams were following Scrum. We first had a look at scaling frameworks, especially since other parts of the company are moving to SAFe but we found that they required too much budget and re-organization for our means (remember, we are just a few motivated developers).

While we were discussing what to do, someone had an idea that was simple, cheap and easy : “Let’s start by doing all our scrum ceremonies together”.

We took the opportunity to add a ‘product’ retro after the teams retros, and a ‘product’ planning just before the teams plannings. We were hoping that regular higher level retros would bring continuous improvement at the product scale and bring in all the other practices required to make it work.

The situation now

It’s now been 2 sprints that we have set this up. Every 2 weeks, Friday is what we call Demo-Day. It’s a meeting heavy day where all the teams have their scrum ceremonies together

  • Product demo
  • Team retros
  • Product retro
  • Product planning
  • Team planning

Sure as hell, 1 day of meetings is exhausting, but unfortunately, it is not possible to efficiently grow a team without increasing the communication overhead. The good side of the coin is that it allows the teams to focus on building valuable stuff during the 9 other days.

Here are the first effects we have seen.

Improved team spirit & product focus

The first noticeable effect was on team spirit. Having a demo and planning for the whole team showed to everyone that we are all pulling towards the same goal. It helped everyone to understand what his current role is in this greater scheme, but also ways to tweak our individual roles to bring more value.

Visible problems

The second good effect is that problems are now visible. If teams are not working in the same direction, it’s visible at the demo and plannings. If a team delivers a story too late for another one to integrated it, it’s again visible at demo and planning.

Another example : after the product planning, Product Managers had to admit that they had not managed to feed high value stories to all teams. They asked to do a pre-planning preparation meeting (which is a standard practice in LeSS for example)

Better continuous improvement

During our first team retro in this setting, we directly stumbled upon on a recurring systemic issue that we never managed to do anything about. Instead of going around in circle on the topic again, we pushed it to the product retro. We worked on another team related problem, for which we scheduled improvement actions.

During the product retro, we raised our recurring unsolved issue. With everyone in place, people higher in the organization had the chance to understand its consequences. Eventually, we managed to come up with concrete actions.

How to do it


There’s only one thing required : that the teams are already following Scrum. All the rest is easy stuff.

This technique is a bottom-up agile adoption. If you want to switch your whole company from waterfall to something more agile, take a look at SAFe.

Organizing the Demo-Day

Here is our planning for our demo day

Time Meeting Who Details
10h – 12h Demo Everyone 30m per team |
12h30 – 14h Team Retro Teams Every team has a different retro in a different room |
14h30 – 15h30 Product Retro Scrum master, volunteers, and decision makers Decision makers are important to be able to take actions |
16h – 17h Product Planning Product managers or owners, volunteers Product people present what they would like to see in the product in one sprint |
17h – 18h Team Planning Teams Every team has a different planning in a different room |

We had to negotiate a bit with other people in the company to get enough rooms for all these meetings at the same time, but all in all, it did not take more than 2 hours.

All meetings are open to anyone, everyone should have the right to come to any of them !

Obviously, that’s a long day ! It’s also full of team energy. In 2 sprints, we found the following improvements :


We pre-order food to be delivered at work, so that we can all eat together. Did you know that food makes retros more efficient ?

Product Retro

You might have noticed that the product retro is only 1 hour long. To make it all fit in one day, we had to cut some time here and there … In order to gain some time on the product retro, we decided to pre-fill its ‘gather data’ phase.

During team retros, if people find product scale issues, they can directly save them for the product retro items (As we are distributed, we use Trello for retrospectives). This way, when the product retro starts, the gather data phase is almost done, pre-filled with genuine points.

Keep the energy high

One full day of meetings is long. People get tired. In order to keep the energy high and the overall experience fun, we deliberately added some fun throughout the day :

  • Energizers at beginning of meetings
  • Board games during breaks
  • End of day celebration outside the office. You could go out and have a drink all together for exemple.

The Timeline board game box

We had fun playing this game between the meetings

Preparing the product Backlog

Depending on your situation, you might (or not) have a prioritized product backlog. My advice is to start with what you have.

If you are scaling your single team to 2, keep a unique backlog for both teams and create 2 feature teams. You’ll be heading to the LeSS organization, which you’ll be able to refer to.

If you are applying this on existing scrum teams with their own backlogs, it might be easier to create a product backlog for the product managers. This is more akin to what SAFe suggests. It’s not as straightforward as having a single backlog for everyone, you’ll need to add some links between team and product stories to be able to track progress. Nevertheless, it provides visibility to everyone. As a side note, this is what we actually did.

Keep in mind that it’s only a starting point anyway, product retrospectives might transform all this down the road any way.

Start where you are now !

The most important thing to do is to start ! There are always a ton of reasons why things are not ready and need more preparation. Remember the agile principles : integrate early and often, adapt, experiment … Here are few examples of bad reasons not to start

  • You cannot get all the good people in the room : start, invite them anyway, and send them a report of what has been decided without them. I cannot promise that’s it’s going to work at the end, but at least, it will create some discussions
  • The product backlog is not ready : start, and see what happens ! It will make it clear to everyone that product backlog is super important. People will organize to provide enough product features next sprint.
  • You need some other regular meetings for X, Y or Z. For example, Scrum of Scrum has daily SoS Meetings. Start anyway, if there’s a need, people will ask for these extra meetings, which will save you some goodwill. You might also discover that you don’t need these meetings at all and save some time !

With a product retrospective every sprint, important issues will get addressed !

Just Do It

Does ‘Agile Scaling’ even exist ?

We did this on 4 teams. I have no ideas how it would work with more teams. We did not use any framework, even though we took ideas here and there. What we really did is to follow the agile principles, for example :

  • KISS
  • Do the simplest thing that could work
  • Baby steps
  • Continuous improvement
  • Experiment

Others have noticed similar things :

Agile scaling frameworks might be a good starting point (the Shu in Shu-Ha-Ri), but only as long as the agile principles and values have not been understood by the organization.

Incremental Architecture, a Cure Against Architecture Astronauts

Back in 2001, when I started to code for a living, fresh out of school, I was mainly doing a form of cowboy coding. After a few months of maintaining my own mess, I started to recall my university lessons : we should be doing design before coding …

When I was asked to re-engineer the ‘wizards UI’, I paused my coding to design something clean from scratch. It worked quite well at first : the overall code was a lot simpler and contained a lot less duplication than before. Seeing this new shiny UI, product people asked for new features. Unfortunately, I hadn’t thought of them when designing this little framework. I was almost back at my initial situation.

That’s how I started to look for another way to design software. At about the same time the eXtreme Programming book fell into my hands. That’s where I discovered the idea of incremental design and architecture.

Front cover of the first edition of the XP book

What is Incremental Archi

Let’s start with the antithesis of incremental architecture :

Astronaut Architecture

The term “Architecture Astronaut” was coined by Joel Spolsky back in 2001. If you haven’t read this classic post yet, I strongly encourage you to do so. Basically, he explains that we should not be impressed by architects going over their heads talking about too abstract stuff.

Incremental is the exact opposite of astronaut architecture

Two Schools to Software Architecture

Traditional architecture is about taking up-front choices that will be difficult to change. Incremental architecture is about preparing for non-stop change and taking decisions as late as possible.

The idea in incremental architecture is really simple : keep your code simple, clean and automatically tested in order to be able to simply adapt your code and architecture when definitely needed.

Pros and Cons of incremental architecture

The first reaction of most software engineers (me included, remember how my story started) is that it can only work on trivial stuff. After practicing it for about a decade, I am now convinced it works most of the time. I’m not alone, James Shore (who wrote the more on the subject) also shares my view:

Common thought is that distributed processing, persistence, internationalization, security, and transaction structure are so complex that you must consider them from the start of your project. I disagree; I’ve dealt with all of them incrementally.

Two issues that remain difficult to change are choice of programming language and platform. I wouldn’t want to make those decisions incrementally!

I would add published APIs to this list.

Granted, there are situations that incremental architecture alone cannot handle, what about its good points then ?

In all the other cases (and that means most of the time), here is what you get :

  • As you won’t need to deal with future use cases, you’ll do less work
  • That in turn, will keep your code simpler, decreasing time to release new features
  • As change is built-in, you’ll be able to improve your architecture in ways you could not have imagined from the start !

Front cover of the Art of Agile Software Development book

If you cannot see how this could possibly work ? Read on !

How to do it

eXtreme Programming

As I said earlier, incremental architecture emerged from eXtreme Programming. It won’t come as a surprise that in order to work well incremental architecture requires the XP practices to be in place. In particular, the code base should be automatically tested, the continuous integration cycle should take less than 10 minutes, the design should be simple. The team should be good at doing refactoring.

Don’t expect to be able to do incremental architecture without these practices in place. But this alone might be enough already !

Front cover of the Martin Fowler's refactoring book

Architecture Vision

At work, where our team consists of 9 developers, it’s not always that simple to coordinate and all pull in the same direction. That’s why we find it useful to share a very long term architecture vision (Enabling Incremental Design and Evolutionary Architecture). This will help people to make coherent decisions when hesitating between 2 alternate designs.

The vision can be the result of the work of a pair, or a mob brainstorming or whatever. Building this vision is typically an activity where experienced programmers can contribute a lot of value.

Once this vision is shared and understood by the team, every time a pair has to work on a story, they can orient the design towards it. But always as little as possible to finish the work at hand, remember the XP motos KISS (Keep It Simple & Stupid) & YAGNI (You Ain’t Gonna Need It.

One final word … a vision is just that : a vision ! It might turn out true, or false, be ready to change it as circumstances change.


At times, even with a story in your hands and a long term architecture sketch on the whiteboard, you might have difficulties to know how to change your design to fulfill both.

As always in XP, in case of uncertainty, use Spikes ! Spikes are short time-boxed experiments of throwaway code, which goal is to answer a specific design question.

How to mitigate the risks

What about these topics that don’t yield to incremental architecture ? What if you discover late that you need to change your platform ? Or your API ?

Obviously, you should think about these questions up-front. Hopefully, there are usually not that difficult to answer. But, over time, Non-Functional-Requirements and technologies change. Large and long living systems are particularly likely to need to change to a new platform someday.

Unix had the answer : build your system out of small tools, that do only one thing well, and that communicate through a standard protocol. Systems built that way can be re-written one piece at a time.

Ken Thompson and Dennis Ritchie, the creators of Unix

Photo from WikiMedia

The modern version of this is the micro-services architecture. Incremental architecture allows you to start with a monolith, split it when you need to, and replace micro-services as needed. With the safety of simple code and a great automated test harness. Interestingly, successful software systems that were architectured up-front also take this road … without the safety !

The Architect

Good news : no more PowerPoints and a lot more coding with the team ! Here is what’s expected from an incremental architect :

  • To code with the team. As Bertrand Meyer once said “Bubbles (aka. diagrams) don’t crash”, it’s plain too easy, and wrong, to mandate architecture without living with the consequences
  • To come up with more ideas when drafting the long term vision
  • To keep an eye on the ‘long term’ while being the navigator in pair programming
  • In the second edition of the XP book Kent Beck suggests that the architect should write large scale tests to stress the system and demonstrate architecture issues to the team
  • To delegate as much as possible to the team. However smart the architect, the team as a whole is smarter ! Delegating architecture increases motivation and the quality of the outcome.

End of the story

I’ve been practicing incremental architecture and design for a long time now. It made my life a lot simpler ! Most architecture questions become backlog items to prioritize.

One last advice : be prepared to re-read Joel Spolsky’s article whenever you get caught up in architecture meetings …

How to Get Your Team to Do Code Reviews

As software developers, we very always often get to work in code bases that are not perfect. In this situation we have 3 choices : leave, grumble, or make some changes ! Team wide code reviews are a recognized way to increase the quality of the code.

Unfortunately, installing code reviews as part of the daily work habits of a team can be very challenging. When I joined my team 3 years ago, no one was doing any kind of code reviews. With a small push here and there, I managed to get the team to adhere to a strict 4 eyes principle (full story here).

Here are a few strategies that I have either used or seen that should get your team mates to do code reviews.

Overall principle

Even if you are at the bottom of the org chart, you have far more influence than you would first think. My favorite way of bringing change is to demonstrate a valuable practice :

  • First, you need to be trustworthy
  • Then, do the practice you want to introduce
  • Make sure it is seen as valuable
  • Be ready to forgo the credits of the introduction of the practice
  • Keep on until people start to copy what you are doing

As someone famous said

A man may do an immense deal of good, if he does not care who gets the credit

I won’t go in the details about how to be trustworthy, which could be a post of its own. Basically, putting our customers interests first, speaking the truth and avoiding to appear dogmatic can get us a long way already. The Clean Coder is an excellent read on the subject.

Front cover of the Clean Coder book


If you have retrospectives in place

In this case, you already have a place and time dedicated to discussing changes to your working agreements. Expressing your concerns about code quality (or another problem related to code reviews) and suggesting code reviews as a way to fix that problem might get a quick team buy-in.

If you don’t manage to get a definitive buy-in, try to get the team to ‘beta-test’ code reviews for a while. If the experiment demonstrates value, it will convert into a full fledged working agreement.

If you practice collective code ownership

Unfortunately, if you don’t have retrospectives in place, or if you did not manage to get your team to discuss code reviews in retrospectives, yo’ll need to find another way to introduce them.

If you have collective code ownership, it should be ok to comment on your team mates code (if not, jump directly to the next strategy). In this setting, just start to do some code reviews for others ! Make sure your reviews are helpful and ‘nice’.

You’ll need to stick to doing code reviews long enough before people actually start to mimic you. Reserve some time in your daily agenda for code reviews. Your goal is to win over people, so it might be a good idea to start with a selected few at the beginning, preferably people who are more likely to jump in. If asynchronous (tool based) reviews don’t get answered, be ready to fallback to face to face discussions : review on your own, then just ask the author for a few minutes so that you can discuss his change. When you feel someone is interested by your reviews, ask him to review your own code in return.

Remember to always try to get some feedback : ask people what they think of the exercise, keep note of the good points, and adapt to smooth out the rest.

Illustration of a team working collectively

Photo from emotuit

Once you won over your first team mate, involve him in your grand plan to spread the practice, explaining how much you think this could make a difference. As more and more people get convinced, the practice will eventually tacitly become part of your working conventions.

Depending on your context, this might take more or less time. I said it was possible, I never said it would be easy ! Grit, patience and adaptation are key here.


This is the worst starting point, basically, you have nothing yet. The strategy is very similar to the one with collective code ownership, with a different first move.

Instead of providing code reviews to your team mates, start by walking over to them to ask for a face to face code review of your own commits. Use the same tactic as stated before : stick to the same people at first. Once the practice starts to stick within this group, bring in a basic tool to ease up the process.

At some point, you should be asked to review others code, that’s a good sign ! If not, try again with other people.

Continue using the same strategy as with collective code ownership and you should eventually get there !

When it does not seem to stick

There could be many reason why the practice is not adopted. The key for you is to understand why and to adapt your strategy. The reason is often that the perceived value is not big enough, for example :

  • the team is not aware of its problems that reviews would fix : try to make them more visible
  • reviews are seen as too expensive or painful : try better tools or taking more on yourself
  • the team has bigger problems to fix first : spend your energy on these first !
  • reviews just don’t work in your context (ex: your job is to write one time, throw away code) : it’s up to you to stay or leave !


There are a ton of tools and best practices to run code reviews. It’s important that you know them, so that you know where you are going.

Don’t expect to use the best tools from the start though. At the beginning, your goal is to win over your team mates. In this context, only 2 things matter :

  • It should have almost no adoption curve, so that others start using it
  • It should have almost no maintenance cost, as you don’t want to spend your time doing that

That’s why at the beginning, low tech tools are so great. Spending a month setting up a top notch code review system before the first review won’t work. If your VCS has code reviews built-in, by all means use it ! Otherwise, diff in mails and face to face conversations are a good starting point. You’ll later hook something in your VCS to automatically send mails with commit diffs …

As people gradually get convinced of the value of code reviews, regularly meet and discuss a better setup. This is how you’ll introduce state of the art tools and agree on refinements such as pre or post commit reviews.

Best practices

As a code review champion, it’s very important that you provide great reviews to your team mates. You must become the local expert on the subject ! You don’t want all your efforts to be ruined because one of your reviews has been perceived as aggressive.

A slide from Atlassian presentation about styles of code reviews

There is a ton of resources on the internet about how to perform good code reviews, here are a few :

What’s next ?

Congratulations ! Your team will start to reap the benefits of code reviews. Keep on improving the practice !

To end the story, after a few months of code reviews, during a retrospective, my team (at work) decided to take it one step further and started to do almost full time pair programming ;–)

A Seamless Way to Keep Track of Technical Debt in Your Source Code

I eventually stumbled upon a way to keep track of technical debt in source code that is both straightforward and already built-in most tools : simple TODO comments !

Photo of a screen displaying source code with #TODO comments

How it happened ?

Some time ago, we tried to add @TechnicalDebt annotations in our source code. Unfortunately, after a few month, we came to the logical conclusion that it was too complex to be effective :

  • It involved too much ceremony, which frightened people
  • It made people uneasy to change anything around the annotation instead of sending a call to action
  • As a result, it was always out of date

After a bit of discussion with my colleagues, we decided to replace all these annotations with simple TODO comments.

When the refactoring to do seems fairly obvious (but also premature) we’ll use a straightforward //TODO (example) introduce a factory message. Next time a pairs gets to work on this part of the code, they get the silent opinion of their peers to help them decide what to do about this piece of the code. Other times, the code might be smelly, yet without us knowing what to do about it yet, in this case, we agreed to use //TODO SMELL (example) responsibilities are not clear in this class which is still a TODO comment, but not a clear call to action.

When I started my current side project, I naturally started to use them. They display nicely in CodeClimate.

The pros

Screenshot of the CodeClimate issue dashboard displaying TODO comments

The great thing about TODO comments is that, as a very old programming trick, they are already supported out of the box by most tools IntelliJ, SonarQube, Rails, CodeClimate and I guess many others. Only one day after I refactored to TODO comments, a team mate fixed one that had appeared in his IDE’s TODO tab !

The cons

Some tools, IDEs in particular, tend to assume that you should fix all your TODOs before you commit anything. That’s not exactly how we are using them to track lasting technical debt. So that’s one thing you need to keep in mind.

Tools like Sonar on the other hand, assign a fixed remediation cost to any TODO you have in the code, which is usually not the case at all !

How to set it up in your project

As you might guess, this is pretty easy. Just start adding TODO comments in your code …


It is worth first validating the practice with your colleagues though. There are many ways to do that, depending on your team’s work habits :

  • Use your team Slack (or whatever chat room you use) to share a link to this post (for example) and create a yes/no poll
  • Or if you think you need it, create some wiki page explaining the practice and detailing its rationals in your context, add a yes/no poll, and finally share this page with your team
  • Eventually, if you think that this topic deserves it, setup a meeting with everyone and discuss the point. It might be worth sharing information about the practice beforehand to make the meeting more efficient. You can end the vote with a thumb vote (up : yes, down : no, side : whatever)

Thumbs voting positions

Don’t wait for unanimity to start the practice, majority is enough ! Make sure that people who voted the other way will follow the team practice in the end though. Remember that whatever the answer, discussing team practices is good.

Once all the team agreed on using (or not) TODO comments, mention the practice in your team’s coding conventions or working agreements (which I strongly recommend to have written somewhere). If you don’t have any yet, create some !


Most tools will handle TODO out of the box.

  • Rails comes with a rake notes task to list TODO comments.
  • CodeClimate and SonarQube both lists TODOs as issues in their default config
  • Most IDEs have a ‘TODO’ tab which will display the TODO comments in the project
  • Otherwise, good old grep will very happily find TODO comments in your code

Some tools might require small tweaks to improve the experience :

  • In IntelliJ, in the commit window, uncheck the ‘Check TODO’ checkbox to avoid getting a warning at every commit

IntelliJ's commit window, with its 'Check TODO' check box

  • SonarQube uses the same fixed remediation cost for every TODO comment. It’s up to you to adapt this remediation cost to your context.

What’s next ?

TODO comments are a good starting point to track technical debt. Once you start using them, there are a few things you can do :

First, remember to fix some regularly. Very old TODO comments are technical debt of their own ! Using code quality dashboards like SonarQube or CodeClimate help to continuously improve your code.

If your tools allow it, you might consider setting up a simpler //SMELL ... instead of //TODO SMELL ... or whatever other special comment that might be useful in your context.

Finally, there is a lean continuous improvement practice which consists of logging problems as they occur. Doing this could help your team to decide which technical debt hotspots are the most important to fix. When appropriate, link the problems with the TODO comments. After a few weeks of this, walking through all the problems during a retrospective should shed light on what parts of the code are causing the most troubles.

Edit 2017-04-19

Thanks a lot for your comments ! People have suggested a ton of great improvements over my basic setup :

  • plugins to other tools that also support TODO comments
  • activating automatic sync between issues in CodeClimate and your issue tracking system
  • using custom comments markers
  • adding an ‘X’ to your comment every time you are bothered by the technical debt, tools can configured to assign a higher severity to issues with a lot of ‘X’