Lava Flow is a programming anti-pattern that occurs when code which works, but isn't well documented or understood by its maintainers, is kept in a system because it works.

In other words, lava flow is any code which is kept around because no one has the time or willingness to understand it, or indeed, even go near it. Such code can be said to "flow" through the system it inhabits.

In the land of Mordor where the shadows lie

The fix for this anti-pattern depends heavily on whether the lava flow has already occurred. My team is directly dealing with this anti-pattern as I write this, even deliberately causing it. We're hoping our preventative measures will be enough to keep the house from burning down.

The Rundown

  • Name: Lava Flow
  • Summary: Code which works and is kept in a project, but is insufficiently documented or understood.
  • Type: Programming
  • Common?: I dunno, but if I try to find out it doesn't work anymore.

Tell Me a Story!

I am standing on the precipice of dealing with a ton of lava flow. My team and I are taking a huge, ten-year-old internal web application and porting it to much more recent technology.

Our current directive, for better or worse, is to port this system as quickly as possible, making no functional changes (because I already know how that goes). That means taking a lot of the legacy code with us, as we don't, right now, have time to determine whether or not it is actually necessary.

And I, as the lead developer, am now forced to stare into the void and hope it blinks. I am watching as my team, slowly but surely, brings all this code and all these methods and all this extra crap into our new system, knowing full well that it's gonna take ages to sort out. I know this, and we're doing it anyway, because this is the real world we live in, and the real world needs working software before it needs correct software.

But I know it's coming. We all know it's coming. So how do my team and I prepare for it?  

We architect, and document, the crap out of it.

Strategies to Solve

If the lava flow code does not already exist, all we have to do is prevent its occurrence. This comes in two forms:

  1. Appropriate architecture, which ensures that code has a reason to exist and, if no such reason exists, allows the code to be removed easily.
  2. Appropriate documentation standards, including writing down when, why, and how methods/classes/fields are used and for what reason they were added.

Handling Lava Flow is all about prevention. But if, like in my situation, the flow has already started, well... then we're gonna have to get a little bit dirty.

The calm before the crying storm.

See, once lava flow code is already in a system, it becomes incredibly difficult to remove, because to do so requires the remover to understand not only what that code does, but how it impacts the rest of the system. This is why lava flow code even exists as an anti-pattern; it's an amalgamation of months or years of tiny decisions, which now falls to some poor sap to sort out. But what happens when you are that poor sap? And, worse, you're making a decision in full knowledge that it's going to result in massive lava flow?

You take steps to minimize damage.

In our case, some of the stuff we're doing is simple. The old project has a single eleven-thousand (yes, 11,000) line file. We are splitting that up into logically-related files, classes, and groups of methods. We know we need Dependency Injection in the new system, and so we are making our new classes smaller and more focused, as best as we can in the time constraints. We're renaming important things to better reflect their purpose, adding documentation that didn't previously exist, and generally moving toward a system in which small, focused classes do one job. We're making progress.

The hope, the goal, is that when the time comes these simple actions will minimize the amount of lava flow we have to deal with. It's worked before, but we've never tried it on this scale, and only time will tell if it's going to work out.  


Lava Flow is code that is dragged along in a system, and is necessary for that system to work, but is poorly-understood or poorly-documented and as such is difficult to remove. My team is staring this problem in the face at this very moment, praying that our preventative measures will be enough to keep our metaphorical house from burning down.

This time, the floor really IS lava.

Let's hope it works.

Are you dealing with lava flow in your projects? Do you have some good ideas on how my team (and others) can manage it, or prevent it more thoroughly? Has your house been destroyed by lava? Share in the comments! Or else head on back to the series index page to see some more anti-patterns.

Happy Coding!