What is the dirty flag design pattern? The dirty flag behavioral pattern avoids work that would need to be done again anyway. This simple pattern explains how to add a bool value to your class that can be set anytime a property changes. This means results need to be re-calculated when they’re requested. The bool value can then be cleared.

Even though this is a simple design pattern, there are some things you’ll need to consider:

  • Do you need it? This design pattern works well when the results to be calculated are difficult or resource intensive to compute. You want to save them. You also don’t want to be calculating them several times in a row when only the last one counts.
  • When do you set the dirty flag? Make sure that you set the dirty flag within the class itself whenever an important property changes. This property should affect the result of the calculated result and by changing the property, that makes the last result invalid.
  • When do you clear the dirty flag? It might seem obvious that the dirty flag should be cleared whenever the result is calculated with up-to-date information. But there are other times when you might want to clear the flag.

Listen to the full audio episode or you can also read the transcript below.

If you’d like to read the book that describes this pattern along with diagrams and sample code, then you can find Game Programming Patterns at the Resources page. You can find all my favorite books and resources at this page to help you create better software designs.


The basic description says that this pattern avoids unnecessary work by putting it off until it’s actually needed. Let the procrastinators rejoice because this design pattern is a perfect fit.

We’ve all been taught to get our work done as soon as possible and avoid putting off what can be done today.

  • But would you wash a coffee cup after every sip?
  • Would you save a document that you’re writing on your computer after every letter typed?
  • Would you prepare your income taxes after every paycheck?

All of these are crazy, right? Nobody would do such thing. But a computer will if you’re not careful.

Of course there’s got to be a balance here.

While you don’t want to save an important document after every tiny change, you also don’t want to wait until the end either. If you lose power or the document editor crashes, then you just lost all the work since the last time you saved your work. Maybe then you’ll wish you had been saving more often.

There are also times where it is better to perform a task right away. Let’s say you have to add up a bunch of numbers and they just keep coming. You don’t even know how many there will be. You could save them somewhere until you have all of them and then add them. But that would be taking this pattern the wrong way. Whenever you can maintain a running total, then you’ll usually be better to just do the work as it comes along.

This pattern helps when the work that you could do right away will become outdated and useless a moment later. And if it takes a lot of resources, either in terms of memory used, or time required, or battery power consumed, to do work that just needs to be redone anyway, then you really should avoid this.

First of all, what is a dirty flag and how can it help?

A flag in programming terms is just a value usually stored as a member variable of a class that is either true or false. Sometimes you’ll hear the terms set and cleared. Or on or off. These all mean the same thing. A flag is nothing more than a boolean value. If your programming language doesn’t support bool data types directly, then you can use a numeric value and store 1 for true and 0 for false. Sometimes this is called a bit because a binary bit also can only be either 0 or 1.

A flag helps anytime you need to remember if something is on of off, if something’s been done or not, or in this case if something’s valid or not. What is that something and what does it mean to be valid?

Anytime you have an object that has something time consuming or otherwise resource intensive to calculate a good way to handle this is to save the result once you actually go through all that trouble. When you wash your dishes, do you put the clean dishes on the floor where they’ll just get dirty again? No, you make sure to keep them clean by putting them away. The same thing applies in programming. When your code takes the time and effort to calculate something, you’ll want to make sure to save that in case it’s needed again.

This is a simple design pattern. But even so, there’s some things you need to consider. I’ll explain what they are right after this message from our sponsor.

( Message from Sponsor )

Let’s take a specific example.

And say you’re working on a word processor that has a feature that allows users to insert a table of contents that can automatically track the page numbers of important sections.

Now, some customer has been using your application for a while and has a rather long document with lots of entries in the table of contents. Your testing revealed that it takes a noticeable amount of time to update a page number in the table of contents. So you decide to save all this information and formatting. This makes it easy and fast to display the table of contents.

What happens when your customer decides to perform an automated text search and delete operation? How will your code handle this?

Here’s what can happen if you don’t implement the dirty flag design pattern.

You start with the first section and place it on page 1. That was easy because it was already on page 1. And let’s say the first section used to need couple pages but after removing the text, the first section now needs 1 page. So you go through each section in the rest of the document and update all their page numbers.

Each section then informs the table of contents that it has a new page number. You haven’t finished the text removal though and now it’s time for section 2. And it turns out that this section also had quite a few instances of the text being removed. Enough to change all the page numbers again.

You just updated the page numbers but since they changed, you go through all the remaining sections and update them again. This causes the table of contents to be updated again too. This pattern repeats until the user exits the application out of frustration. Never to use the app again.

And you know what makes this even more tragic? The user wasn’t even looking at the table of contents during this time.

Okay, so how will the dirty flag design pattern make the situation better?

When the sections are asked to change their page numbers, they still update the table of contents with their new page number. But this time, instead of the table of contents doing a bunch of formatting and arranging, it just sets a flag to true and returns. This flag lets the table of contents know that its saved formatting is no longer valid. But it won’t start reformatting the table until some code asks for the new format.

Your code can now go through each section and replace the text all it wants. Each section will inform the table of contents that it has a new page number but all that expensive work of reformatting the table will be skipped.

Here’s an important aspect of this design pattern.

You don’t modify the value of the dirty flag directly.

You let the class that implements the dirty flag set and clear the flag as a result of some other property that changes.

I remember once a project that I worked on for a large company and I was integrating an anti-virus library into the application. Now anti-virus software is very complicated with lots of configuration settings that control exactly how it behaves. Most of this complexity is taken care of for customers by the application. But I needed to change a configuration and was trying to figure out why the anti-virus software wasn’t working properly.

It seemed to behave randomly until the computer was restarted. It took me a while to figure out that there was a dirty flag that I was supposed to set anytime my code changed a configuration. It seemed to behave randomly because I was testing different combinations and the anti-virus software would eventually update its state but it was always one configuration setting behind what I was testing.

Just remember when you implement this design pattern. Don’t make other developers set your dirty flags for you. When you notice that one of your class property values has changed, go ahead and set the dirty flag yourself inside the class. The dirty flag is an implementation detail that only the class using it should know about.

Now that you know how to set the flag, when do you clear it?

You have a few choices.

  1. You can clear the dirty flag right after some code requests the result of the expensive operation. Before returning your saved result, check if the dirty flag has been set and if so, then throw away the old result, recreate it, and then clear the dirty flag. This makes sure that the latest information is always available when needed and avoids recalculating the result when it’s not needed.
  2. You can check the dirty flag at specific times or convenient moments and decide to start whatever expensive operation needs to be performed. This can sometimes be a little hard to judge when is a good time. But if you have this scenario, then this can be a good choice because the new results can be ready the moment they’re needed. You might sometimes recalculate the results when not needed.
  3. You can update the results and clear the dirty flag in the background when your application has some extra time. If you go with this, just be aware that you may still need to use one of the first two options.