Kind of depressing to read because it's so accurate, yet so likely to be ignored.
I remember when Martin Fowler first published the book "Refactoring" - I was so relieved at the time because somebody with some clout that executives might actually listen to had not only identified what was wrong with software but identified a way to fix it and even gave it a name! Boy was I wrong - now you have to be careful how and when you use the term "refactor" because the people who ought to be supportive hear "wasting time".
Part of this is on developers. Refactoring is fine, but too often it turns into yak-shaving and nothing ships. The approach usually works: refactor in small steps and tie it to a feature so it’s testable and adds value.
Very much this. There's no need (and certainly never time) to add tests to the world or refactor everything. But it's often practical to figure out "I need to make changes "here" and add tests for that section and do whatever cleanup helps for that bit.
This is on the engineers. Asking for time to refactor is like a painter asking for time to prime. It’s part of the job so just do it. When brought out in discussion, it sounds as if it is optional and its value dubious. That’s where the feeling of “wasting time” comes from.
Additionally, a lot of refactoring is about predicting the future rather than adapting the code to present expectations while keeping things easy to change. The only metric that your future self cares about is time to feedback. Refactor to adapt to present expectations while keeping the code easy to change in the future, and don’t ask for permission to do this- it is your job.
Nowadays people throw the term "refactoring" around quite loosely, usually meaning "rewrite" when that was not at all the original meaning of the term!
A little bit like how "vibe coding" quickly went from one definition to another even though people should have known better.
My feeling about it is that there is not a tension between refactoring and feature work but rather that a specific bit of feature work is best done with a refactoring. For instance about 10 components on a certain page I was working on all had the same accessibility problem which involved changed the HTML and then changing the CSS so this is a good chance to make a single component which can be used to replace the problematic code in all 10 components and to rationalize the CSS.
Yes, I have the same experience. Most of my features are implemented as double figures of tiny refactoring commits to prepare the code so that the feature can be implemented in a straightforward way.
I understand and I agree with the author points, specially looking to distance yourself from the dependencies these systems are usually entangled with, however:
>But the code examples are in Java and C++ and I do python/JavaScript/ruby/
The problem with real legacy code is that sometimes it's not even in those languages. It's VB.NET, COBOL, AS400, BASIC, FORTRAN...and these may not have a chance to "wrap around your class", or "think about all the ORM code that you use". None! I use none of that!. And I can't even call any tests because I can't extend a non existant class, there's no objects in here!.
The author also says:
>You need feedback. Automated feedback is the best. Thus, this is the first thing you need to do: write the tests.
I don't need automated feedback. I need to untangle this deep business layer that everything is wrapped around in a 40 years old codebase, with practically no documentation and having to modify one of the core systems of the company. Sometimes I can't even trust the feedback the program outputs. In this kind of scenarios where the code is so messy and limited by technical factors, the best approach I have found is to debug. And that's it. Follow the trail, find the "seam", and then start your kingdom in the little space you can. Because if you tell your boss that you are implementing Unit tests in a 40 years old codebase, the first question he is gonna hit you with is "Why?", and the article doesn't give any compelling argument to answer this.
Would you be so lucky if your legacy code was written in a well-known language. At a previous employer we had a big pile code in a “macro” language. It could interface with the main C++ code base. It was similar to assembly language in that it had no loops (just gotos) and register-like local variables (no custom names, just L0, L1, L2,…). The semantics were weird, something like unexpected pass-value-value versus pass-by-reference behavior when calling functions.
One customer required lengthy qualification processes when changing the software. But “configuration changes” had a lower bar and somehow these “macros” counted as config. So eventually all the interesting business logic and RPC processing end up in a giant macro file.
Sounds similar to, but not as bletcherous as, BANCStar, a famed "esolang" that was really the output of a form generation tool used in the finance industry in the 90s. Some engineers figured out that the form generator's output was actually expressed in a Turing-complete, though very arcane, notation replete with opcodes and operands, reverse-engineered it, and started working directly in this language without using the tool to do more sophisticated things than the tool enabled on its own. The boss man probably said "Great! When can we put this into production?" and it's been downhill since.
Relatedly, a long time ago I discovered that Zenographics Mirage—a vector graphics/illustration program originally designed to run on like, VAXen, with both a text terminal and a graphics terminal with a digitizing tablet (similar to this setup seen on Reading Rainbow: https://www.youtube.com/watch?v=b_zYaIxb6dY&t=965s), but later ported to PCs—ran on a sort of bytecode. There were a number of sample scripts shipped with the package that allowed you to automate things in Mirage's command language. Some of them had statements like DO 62,2,32472,32476,0 and comments that read "Don't worry about this, this is just Mirage assembly language." Intrigued, I discovered in the manual a feature you could enable called Op Code Monitor that flashed similar numbers whenever you entered a command. It was mentioned but not documented in detail, nor what the numbers meant, but from that and the scripts I could make some pretty good guesses. I figured out how to make Mirage prompt for a point and store it in a register; and with that I made a command to draw a rectangle that could be rotated. A rectangle in Mirage was defined by its corner points, so when you attempted to rotate it it just rotated the corner points and drew an axis-aligned rectangle with the new corner points. My command accepted two corner points and drew a polyline, so that when you rotated it, the whole rectangle rotated.
From personal experience with bosses: no, often times it's not a sufficient argument.
If the choice is thought to be between:
* delivering value directly to the customer to justify a company's existence
* or adding tests to things that already work (shore up) in an effort to make more correct changes in the future
Will anyone be surprised how often it's the former that management will go for?
I've found the appetite for this type of testability/observability improvement work increases proportionally with the number of support calls being made from customers complaining about the current feature set being unstable and buggy. This work is less palatable when customers really are just looking for that next new feature you promised instead and everything else is a-ok. The exception being things like orbital navigation systems etc..
That's because you're not opening Jira tickets titled Refactor Foobar. You're just doing it as a consequence of resolving real business issues. I have seen developers, and once been the developer, suggesting a refactor to the PM. That rarely works: it does not (directly) address a business goal.
I read the book shortly after it came out, when I was working on an enormous system of legacy code. Unfortunately, I didn't find the book particularly helpful in terms of strategies for understanding or modifying legacy code. Yes, tests are a good thing, but I expected the book to provide a lot more.
I agree with the parent comment that it is useful to follow the "trail" through the code. It can be a big effort just to figure out how the pieces are connected. Figuring out the data structures and files is another important thing. Also, write documentation as you go; this will help others understand the big picture. If you can just jump in and start writing meaningful unit tests, your legacy system is kinda trivial :-)
Overall, there are people who view testing as a useful tool and people who view testing as an ideology. This book falls into the latter category.
I've skimmed the source material and it doesn't either except for the general advice of putting it all in some kind of conceptual box and slowly move parts to modern or better managed solutions as you try to reverse engineer it all. The underlying subtext was that it is all probably worse than you think and there isn't much good news... But "containment" in various forms is the direction forward mostly unfortunately.
> And I can't even call any tests because I can't extend a non existant class, there's no objects in here!.
I'm gonna preach for the church of "away with unit tests": so what? You don't want to test code. Code is not what the user care about.
You want to test behavior. And for this you don't need to extend classes. You should not have to rewrite any code from your application. Like you say: write tests at the seam. Automate user inputs and checking outputs.
A good test suite should not need to be rewritten during refactoring. It should even allow you to change language or replace for an off-the-shelf solution you did not write. If a unit test suite does not allow that, unit tests are an impediment. And I don't care about the "test pyramid", like the IRL ones, it is just a relic; from an age when launching all your tests in parallel was unfathomable.
> You don't want to test code. You want to test behavior. A good test suite should not need to be rewritten during refactoring.
100% agreed.
> I'm gonna preach for the church of "away with unit tests"
I disagree with the semantics here.
From the article: "In short, your test is not unit if it doesn’t run fast or it talks to the Infrastructure (e.g. a database, the network"
This says _nothing_ about what part of the app structure you test. It's not always a class-method test. Outside-in, behaviour centric tests that are not close-coupled to structure, can also be unit tests. And most of the time, it's a better kind of unit test.
Kent Beck said many times: "tests should be coupled to the behavior of code and decoupled from the structure of code."
"test behavior" was the original intent of unit tests. The idea that unit tests are only close-coupled class-method tests, or that testing 2 collaborating classes from the same app at once counts as an "integration test" is a latter-day misconception. A dumbing down.
I read through this book relatively recently and agree with the praise here for the core idea that legacy code is code that is untested. The first few chapters are full of pretty sharp insights that you will nod along to if you've spent a decent amount of time in any large codebase.
However, most of the content in the last half of the book consists of naming and describing what seemed like obvious strategies for refactoring and rewriting code. I would squint at the introduction to a new term, try to parse its definition, look at the code example, and when it clicked I would think "well that just seems like what you would naturally choose to do in that situation, no?" Then the rest of the chapter describing this pattern became redundant.
It didn't occur to me that trying to put the terms themselves to memory would be particularly useful, and so it became a slog to get through all of the content that I'm not sure was worth it. Curious if that was the experience of anyone else.
Thanks. After I wrote it a friend said "I think you just gave people permission to do things that they would've felt bad about otherwise." I think he was right, in a way. On the other hand, not everything is obvious to everyone, and it's been 20 years. Regardless of whether people have read the book, the knowledge of these things as grown since then.
> It's harder if they can't read the older examples, but I can google for a more modern example as well. It gives nomenclature and examples.
Don't do that. Ostensibly you're giving these people the book so that they'll learn to deal with legacy code. Those older examples are exactly what they need to see, even if they're in a language that those devs are not using.
Junior developers in javascript codebases of 7-10 years old will not have the experience necessary in some cases. I am coaching them as a manager trying to introduce a concept, not a professor.
I may be doing a disservice to their long term development at the cost of short term gains. However, I don't think this is true. There are a lot of developers who will never work in a C, C++, C#, or Java codebase. And I try to adhere to Krashen's "comprehensible input" theory as it has a lot of application to learning the language of software development as well.
I happen to read this book in my early career. I was mid-level. Beyond struggling with codebases, but hadn't yet developed an intuition with codebases. This book blew my mind then. It gave me whole new ways to thinking. I recommend it all the time to people in early career because how to handle a massive legacy codebase isn't obvious at all when you haven't been doing it for a long time.
All the blockquotes are coming in as black on black for me in Safari, Firefox, and Chrome. This appears to be due to a css file called "https://understandlegacycode.com/_astro/ai-support.D3anziw5....". Anyone wanna lay odds on whether that filename is a big tell that much of the text is also written by three autocompletes in a trenchcoat?
I've replaced a few large legacy systems over the years and I disagree with most of the points mentioned in the link. The only way guaranteed to work is to run the old system concurrently with the new system with live inputs and compare results for a trial period and fixing discrepancies as they arise. Only when there is 100% behavioral/data fidelity with the old system can a switchover to the new system occur.
Better still, lots of mini-switchovers. I rolled out a bank’s p&l system for bonds that way. Trading book by trading book, those with simpler instruments first, more complex ones later. We finished ahead of schedule!
You're assuming the "legacy" system is being replaced by a new one, which isn't the scenario being described in the link or the book. They cover approaches for continuing to safely evolve the legacy (i.e. untested) system.
Rewriting the legacy system is one of the valid paths to maintain it. There can be multiple reasons to do that like operational risk which cannot be mitigated, maintenance overhead, risk related to the existing dependencies of the system.
Let me be clear about the situation Mr. Moneybags. You have built a billion-dollar company on top of a giant legacy codebase without any tests.
Now that it's become clear that the thing is about to collapse in on itself, you've brought in Mr. Feelgood Consultingman, to give us engineers generic advice, so that suddenly it's not your fault that this digital superfund site is in the state it is, but your engineers' for not following the consultants advice.
I once had to replace a PostgreSQL-interfacing layer of a large+complex+important system, and most of the original tests had been lost.
It's the kind of change that could be an existential risk for a company that needs the system to be available and correct.
So I built a comprehensive test suite for the existing PostgreSQL-interfacing layer, tested it, made drop-in compatible API using the new way to talk with PostgreSQL, tested that, and... the entire huge system simply worked with the replacement, without a lot of headache/defects/dataloss/ulcers.
> Before you change code, you should have tests in place. But to put tests in place, you have to change code.
Keep reading. You don't always have to do it in the heroic way the article described in this section. Modularity and backward-compatible interfaces, FTW, when you can. The "Sprout" and "Wrap" techniques that the article describes later.
Also, one complementary general technique that the article didn't get into is that sometimes you can run two implementations in parallel, and check them against each other. There are various ways you can do this, involving which really implementation really takes effect, and what you do if they don't agree. (Related: voting configurations in critical systems.)
> Characterization tests
The test suite not only let me validate the implementation, but the exercise of developing the test suite also helped me understand exactly what I should be implementing in the first place.
Sometimes I had to look at the implementation, to tentatively figure out the semantics, then testing validated that also.
> Use scratch refactoring to get familiar with the code
In reasonable cultures and with reasonable management, or if you don't tell anyone. Otherwise, it's the same kind of risk as the old "throwaway prototype" problem: someone with authority says "looks good; I told the customer/CEO we just need to make these few more changes, and ship it". Or, in popular Agile/Scrum processes, "I thought you already completed the refactor last sprint; why are you doing it again".
This book is extremely overrated because the whole thing can be summed up in two bullet points:
* write your new code somewhere outside the main solution and call it from the old solution
* automated tests are pretty cool and you should write these whenever possible
I found the book to be close to useless when I was working with actual legacy code. How do I write an unit test for an application that has an embedded Visual Basic script support with dozens of scripts that are thousands of lines long? The book does not answer this question at all because the author assumed I have the luxury of working with Java or an another language that supports the object-oriented paradigm and can be endlessly extended with no limitations whatsoever.
>How do I write an unit test for an application that has an embedded Visual Basic script support with dozens of scripts that are thousands of lines long? The book does not answer this question at all because the author assumed I have the luxury of working with Java or an another language that supports the object-oriented paradigm and can be endlessly extended with no limitations whatsoever.
Why does the idea of identifying seams not apply to Visual Basic Script?
I've never worked with Visual Basic Script, but I don't see why Feathers' strategy wouldn't apply.
I agree that modernizing legacy code is easier in languages like Java, but I don't think it's strictly necessary. I've used Feathers' techniques for testing C code.
The code base I work on has multiple layers of wrapper code from people following this sort of advice. Sure, it's safe, but once the code is two layers of wrappers deep, you'll see the downsides.
I feel like there is a need for a new paradigm on navigating code; and reference documentation for that matter.
I like how https://gwern.net and https://en.wikipedia.org allow you to hover over terms and show you a quick glance of a term you might not know, and then you can fan out to create an understanding for the basis needed to understand the material in front of you. I feel like some sort of windowing system where I can pin and move references around and then kinda have the llm explain or reference things might be of use to me, as in help me navigate the unknown. Is there a "study companion" application of the sort?
I find that this is easier to do with a language like Java than say Python, I need as much information as I can in order to understand the decisions that led to the current implementation.
Sometimes when I want to change some piece of legacy code, I need to know the rationale behind the code written here, although keeping the interfaces the same and changing the implementation allows me to go quite far.
Legacy code is code you didn't write. It used to be that code you didn't write was written by past team members. These days, we have legacy-code-generators that write code you didn't write at a much higher rate then your company can fire team members.
It's easy to say 'write tests', but it's difficult to do so if you don't know what the actual requirements are.
People often think they are doing it 'properly' now by starting simple, but as they learn more and add functionality, they end up with the same complex mess they wanted to avoid.
Big caveat that I’ve not read the book but I get that the premise is “legacy code is code that is untested” and I’ve always struggled with that definition. I think a more accepted definition would be that it is not well understood, uses old tooling/languages/runtimes and is usually high stakes code (driving some business that was successful enough to last longer than the staff that coded it up). I’m sure added tests help deal with legacy code under that definition but not sure it’s the panacea, I’ve certainly seen code without tests lots very high coverage that people area afraid to work on due to them being unfamiliar with the domain and codebase.
Love this resource, really looking forward to perusing the full text.
And to echo what others are saying I have spent the last month experiencing for the first time how not simple throwing a meaningful test suite together is for a ginormous legacy codebase. I was glad the author briefly seemed to acknowledge that but still... the pain...
They said the playwright ui was supposed to make it easy... Just plug it into an LLM they said... It should just take a few days right?
No. Run away from any sort of refactor or rewrite. Don't even think about it. Do not proceed. If you're thinking that you can do better, you will be humbled in the worst way. Ignore my warning at your peril. I'll never again for the rest of my life make the horrible mistake of rewriting any system. The article's tactics are all good advice – but it's like tactics for surviving on the front line. You win by never going there in the first place.
I think the riskiest migrations are the ones where migration is done in parallel. Internal org power struggles get leaked, whole teams are lobbying against the effort. And on top of all of that rediscovering many things all over again. That in response to cases where a company might decide that the fix too all legacy -> new system is by throwing more money at the problem.
The only issue I have with writing tests before refactoring is that sometimes it can take a really long time to write those tests and cover all the cases, not to mention needing to sometimes refactor to make the code even testable.
I've made huge successful refactors using nothing but carefulness and manual testing, maybe just a very little bit of unit testing :)
I like to make the distinction that the absence of automated tests is not the absence of tests altogether, and that the time it takes to get an automated test set up might be longer than doing the test manually. This is especially important to be aware of if the tests will be temporary because the code is about to be changed.
Of course the goal is to reach an end state with automated tests, but insisting on 100% automated tests up-front can actually prevent the refactoring from even starting.
I would argue that legacy code has more chance of going along with test code than new code. Often code is written and tests grow during its maintenance.
Another thought... if I'm tasked with maintaining or adding features to existing code, should I feel responsible for writing tests for the existing codebase?
- There is usually a "test" folder, but what they test look nothing like the actual code, they often don't even compile, and if they do, they fail, and if they don't, that's because every failing test is disabled.
- Refactoring? What refactoring? Usually, all you see is an ugly hack, usually noticeable because the style is different from the rest of the code base. The old code is generally commented out if it is in the way, left alone as dead code if it isn't.
- Writing tests yourself? It would require you to put the test framework back in order first, they don't have the budget for that. Something as simple as reformatting the function you are working with is already a luxury.
- Sometimes, some refactoring is done, but that's only to add new bugs as to keep things exciting.
Still, as surprising as it may seem, I actually like working with legacy code. It is a challenge, understanding what it is doing (without reading the documentation of course, as if it exists, it is full of lies) and trying to leave it in a better state than it was before in a reasonable amount of time. It is great at teaching you all the antipatterns too, very useful if you end up in a greenfield project later on and you don't want it to end up like all the legacy code you have worked on before. If people actually use it, it will, but you can at least delay the inevitable.
> Another thought... if I'm tasked with maintaining or adding features to existing code, should I feel responsible for writing tests for the existing codebase?
Do you trust yourself enough to not break existing code while maintaining or adding features to it? What would be the consequence of you screwing up? Where would your screw up get noticed? Is it a scary person or group of people who will chase you down to fix it?
I've worked long enough to not trust myself at all anymore, regardless if it's old code or new. Then I evaluate according to above. Usually I land firmly in "yeah, better test it"-territory.
The goal of existing and new functionality is reliability.
What you touch will be on you. So writing a test for your own things, and testing what you are using of the legacy code as you go is a good way to maintain your own coverage in case someone else breaks something in the legacy code, or maybe an update to a library or something goes sideways.
Since you'll be doing a good job of mapping it out below is something elsee. The nice thing is LLMs can help a lot with writing tests.
Reliability can be achieved in a number of ways.
Where I've come across an unknown spreadsheet gone wild, or a code base who's jedi knights have long since vacated, I try to get a sense of putting together the story of how the project started and how it got to where it is today.
If I was cold, I'd first focus on the most critical parts, the most complex, and most unknown potentially to put testing around first.
If refactoring was a goal, for me that means it has to run the same as the old code. One way to do that is see if the existing code can become a service that can be compared to the new service.
LLMs have been really fascinating for me to apply in this regards because I've had to map and tear apart so many processes, systems, integrations and varying interpretations and memories.
AI can even explain what most code is doing no matter how convoluted it is. From there, things like test driven development, or test driven legacy code stabilization is much more doable and beneficial not just for the legacy code, but keeping the AI behaving if it's helping with coding.
>Another thought... if I'm tasked with maintaining or adding features to existing code, should I feel responsible for writing tests for the existing codebase?
Write tests for new additions to the code, when making major overhauls to sections of it, or when a bug is discovered that the old tests did not catch.
Those are the 3 cases I would say you should add a test.
#3 is most important, in my experience.
This book talks about unit tests, but for UI they are mostly useless. I found that for UI the most essential refactoring tools are storybook and visual diff tests.
I remember the time when we had to delete “a lot” of UI tests because the implementation and the framework deprecated and we had to move forward (usual stuff, eg vulnerabilities). Refactoring all of those tests would require a bunch of effort therefore we stopped adding new features and just waited for the last customer subscription to expire, then we moved to other more important stuff.
I recently talk therapied some legacy code through Claude Code back to life, but along the way put some frameworks in place for the codebase itself, and overall with how I think about approaching existing implementations, which helped a ton to shed a path forward for modernization.
It ultimately reminded me there's always a ton more to learn and think about, and it's sometimes quickest to learn from others experiences when considering paths forward, so the book is a helpful share, thanks.
All code is eventually legacy code in one way or another, whether it's the code directly, or the infrastructure level. Today's code might be the best one writes today.. looking back in 5-10 years.. one might wonder if best practice was best practice.
This reads like a blog written by someone who sells expensive consulting for business critical issues, but not to actually solve them, but dispense Eastern Wisdom to the poor developers facing and impossible and unsavory task. This sounds like this was written by a guy who was never directly responsible for producing actually usable and productive results.
This is done so management can lay back and say they already did their due diligence, now you know how to do it, now off to the mines! And be ready by the end of next week!
First:
If your codebase doesn't come with tests you are fucked. There's no possible way you can refactor anything without angry customers calling next day you broke their use case. I worked on legacy code that did come with tests (or even better, well written docs!) And even then it was basically everyday that we broke some elaborate use case checked by the tests.
Management will never approve of a refactor, and with good reason.
> unit tests are fast and reliable
They are also often worthless, because they don't capture real world behavior. Not always but having to mock out half your codebase (including libraries you couldn't possibly know how they work, like a legacy version of Qt your app depends on). You end up with five hundred lines of mock for ten lines of test and it doesn't even give you confidence in anything. These workshy consulting ghouls often force devs to write unit tests, who full well know they're going to be absolutely worthless.
Because you have no idea how it's supposed to work.
> Don’t make your code depend on libraries’ implementation
Good advice , though isn't the definition of legacy code that its already written and after refactor it should keep working like it already did? If somebody before you pulled in a COM object from Microsoft Excel 2003, and your ERP system pivotal to your companies success relies on the exact behavior of that component, where does that leave you?
However, the big problem with legacy code is always political. And the only book I've seen ever try to address that is "Kill It with Fire".
It's one of the few books that talks about the need to keep your team motivated and plugged into the political system given that they are working on the thing that's super important but also almost invisible. You need to be constantly selling what is going on in front of the important eyeballs.
Unfortunately, a lot of the anecdotes have an undercurrent of "Until the system has actively exploded into a million pieces such that somebody with real power has their ass on the line, don't bother."
What sort of LLM/Copilot advice file could you write to encapsulate all the good advice here?
Would "approach this problem using the ideas from Michael Feather's book Working Effectively With Legacy Code" work?
Kind of depressing to read because it's so accurate, yet so likely to be ignored.
I remember when Martin Fowler first published the book "Refactoring" - I was so relieved at the time because somebody with some clout that executives might actually listen to had not only identified what was wrong with software but identified a way to fix it and even gave it a name! Boy was I wrong - now you have to be careful how and when you use the term "refactor" because the people who ought to be supportive hear "wasting time".
Part of this is on developers. Refactoring is fine, but too often it turns into yak-shaving and nothing ships. The approach usually works: refactor in small steps and tie it to a feature so it’s testable and adds value.
Very much this. There's no need (and certainly never time) to add tests to the world or refactor everything. But it's often practical to figure out "I need to make changes "here" and add tests for that section and do whatever cleanup helps for that bit.
This is on the engineers. Asking for time to refactor is like a painter asking for time to prime. It’s part of the job so just do it. When brought out in discussion, it sounds as if it is optional and its value dubious. That’s where the feeling of “wasting time” comes from.
Additionally, a lot of refactoring is about predicting the future rather than adapting the code to present expectations while keeping things easy to change. The only metric that your future self cares about is time to feedback. Refactor to adapt to present expectations while keeping the code easy to change in the future, and don’t ask for permission to do this- it is your job.
> now you have to be careful how and when you use the term "refactor" because the people who ought to be supportive hear "wasting time".
Programmers had a hand in this, sadly: https://martinfowler.com/bliki/RefactoringMalapropism.html
Nowadays people throw the term "refactoring" around quite loosely, usually meaning "rewrite" when that was not at all the original meaning of the term!
A little bit like how "vibe coding" quickly went from one definition to another even though people should have known better.
My feeling about it is that there is not a tension between refactoring and feature work but rather that a specific bit of feature work is best done with a refactoring. For instance about 10 components on a certain page I was working on all had the same accessibility problem which involved changed the HTML and then changing the CSS so this is a good chance to make a single component which can be used to replace the problematic code in all 10 components and to rationalize the CSS.
Yes, I have the same experience. Most of my features are implemented as double figures of tiny refactoring commits to prepare the code so that the feature can be implemented in a straightforward way.
It's not a phenomenon specific to refactoring. Humans just arent good at appreciating abstract gains or abstract risks.
The proliferation of technically clueless managers of tech projects and their "control systems" such as scrum has exacerbated the problem.
I met some doctors recently that made some rhyming complaints when non-medical mba management took over a practice.
I like Fowlers writings, but honestly Refactoring is one of the worst tech books I have read.
Can you say on what ways? I enjoyed it but I'm always keen to revisit my opinions.
I understand and I agree with the author points, specially looking to distance yourself from the dependencies these systems are usually entangled with, however:
>But the code examples are in Java and C++ and I do python/JavaScript/ruby/
The problem with real legacy code is that sometimes it's not even in those languages. It's VB.NET, COBOL, AS400, BASIC, FORTRAN...and these may not have a chance to "wrap around your class", or "think about all the ORM code that you use". None! I use none of that!. And I can't even call any tests because I can't extend a non existant class, there's no objects in here!.
The author also says:
>You need feedback. Automated feedback is the best. Thus, this is the first thing you need to do: write the tests.
I don't need automated feedback. I need to untangle this deep business layer that everything is wrapped around in a 40 years old codebase, with practically no documentation and having to modify one of the core systems of the company. Sometimes I can't even trust the feedback the program outputs. In this kind of scenarios where the code is so messy and limited by technical factors, the best approach I have found is to debug. And that's it. Follow the trail, find the "seam", and then start your kingdom in the little space you can. Because if you tell your boss that you are implementing Unit tests in a 40 years old codebase, the first question he is gonna hit you with is "Why?", and the article doesn't give any compelling argument to answer this.
Would you be so lucky if your legacy code was written in a well-known language. At a previous employer we had a big pile code in a “macro” language. It could interface with the main C++ code base. It was similar to assembly language in that it had no loops (just gotos) and register-like local variables (no custom names, just L0, L1, L2,…). The semantics were weird, something like unexpected pass-value-value versus pass-by-reference behavior when calling functions.
One customer required lengthy qualification processes when changing the software. But “configuration changes” had a lower bar and somehow these “macros” counted as config. So eventually all the interesting business logic and RPC processing end up in a giant macro file.
Sounds similar to, but not as bletcherous as, BANCStar, a famed "esolang" that was really the output of a form generation tool used in the finance industry in the 90s. Some engineers figured out that the form generator's output was actually expressed in a Turing-complete, though very arcane, notation replete with opcodes and operands, reverse-engineered it, and started working directly in this language without using the tool to do more sophisticated things than the tool enabled on its own. The boss man probably said "Great! When can we put this into production?" and it's been downhill since.
https://esolangs.org/wiki/BANCStar
https://github.com/jloughry/BANCStar
Relatedly, a long time ago I discovered that Zenographics Mirage—a vector graphics/illustration program originally designed to run on like, VAXen, with both a text terminal and a graphics terminal with a digitizing tablet (similar to this setup seen on Reading Rainbow: https://www.youtube.com/watch?v=b_zYaIxb6dY&t=965s), but later ported to PCs—ran on a sort of bytecode. There were a number of sample scripts shipped with the package that allowed you to automate things in Mirage's command language. Some of them had statements like DO 62,2,32472,32476,0 and comments that read "Don't worry about this, this is just Mirage assembly language." Intrigued, I discovered in the manual a feature you could enable called Op Code Monitor that flashed similar numbers whenever you entered a command. It was mentioned but not documented in detail, nor what the numbers meant, but from that and the scripts I could make some pretty good guesses. I figured out how to make Mirage prompt for a point and store it in a register; and with that I made a command to draw a rectangle that could be rotated. A rectangle in Mirage was defined by its corner points, so when you attempted to rotate it it just rotated the corner points and drew an axis-aligned rectangle with the new corner points. My command accepted two corner points and drew a polyline, so that when you rotated it, the whole rectangle rotated.
> the article doesn't give any compelling argument to answer this
Is "[w]hen code is not tested, how do you know you didn’t break anything?" not a compelling argument to your boss?
From personal experience with bosses: no, often times it's not a sufficient argument.
If the choice is thought to be between:
* delivering value directly to the customer to justify a company's existence
* or adding tests to things that already work (shore up) in an effort to make more correct changes in the future
Will anyone be surprised how often it's the former that management will go for?
I've found the appetite for this type of testability/observability improvement work increases proportionally with the number of support calls being made from customers complaining about the current feature set being unstable and buggy. This work is less palatable when customers really are just looking for that next new feature you promised instead and everything else is a-ok. The exception being things like orbital navigation systems etc..
>Will anyone be surprised how often it's the former that management will go for?
I don't think I have ever asked permission to do make what I thought was the correct change.
That's because you're not opening Jira tickets titled Refactor Foobar. You're just doing it as a consequence of resolving real business issues. I have seen developers, and once been the developer, suggesting a refactor to the PM. That rarely works: it does not (directly) address a business goal.
I read the book shortly after it came out, when I was working on an enormous system of legacy code. Unfortunately, I didn't find the book particularly helpful in terms of strategies for understanding or modifying legacy code. Yes, tests are a good thing, but I expected the book to provide a lot more.
I agree with the parent comment that it is useful to follow the "trail" through the code. It can be a big effort just to figure out how the pieces are connected. Figuring out the data structures and files is another important thing. Also, write documentation as you go; this will help others understand the big picture. If you can just jump in and start writing meaningful unit tests, your legacy system is kinda trivial :-)
Overall, there are people who view testing as a useful tool and people who view testing as an ideology. This book falls into the latter category.
>> Yes, tests are a good thing, but I expected the book to provide a lot more
It is strange, actually, how much value we place on any information that sits between two pieces of cardboard.
Wait till you hear about how much we value information stored in meat!
I've skimmed the source material and it doesn't either except for the general advice of putting it all in some kind of conceptual box and slowly move parts to modern or better managed solutions as you try to reverse engineer it all. The underlying subtext was that it is all probably worse than you think and there isn't much good news... But "containment" in various forms is the direction forward mostly unfortunately.
TBF, that approach works and you won't go years w/o any deliverables with that approach.
> VB.NET
*laughs in VBA*
I got started professionally in ASP/JScript. That's right, ADO through JScript, backend programming in javascript circa 2001.
(If you've never heard of JScript, be thankful. It was microsoft's very-slightly-modified ECMAscript variant)
> And I can't even call any tests because I can't extend a non existant class, there's no objects in here!.
I'm gonna preach for the church of "away with unit tests": so what? You don't want to test code. Code is not what the user care about.
You want to test behavior. And for this you don't need to extend classes. You should not have to rewrite any code from your application. Like you say: write tests at the seam. Automate user inputs and checking outputs.
A good test suite should not need to be rewritten during refactoring. It should even allow you to change language or replace for an off-the-shelf solution you did not write. If a unit test suite does not allow that, unit tests are an impediment. And I don't care about the "test pyramid", like the IRL ones, it is just a relic; from an age when launching all your tests in parallel was unfathomable.
> You don't want to test code. You want to test behavior. A good test suite should not need to be rewritten during refactoring.
100% agreed.
> I'm gonna preach for the church of "away with unit tests"
I disagree with the semantics here.
From the article: "In short, your test is not unit if it doesn’t run fast or it talks to the Infrastructure (e.g. a database, the network"
This says _nothing_ about what part of the app structure you test. It's not always a class-method test. Outside-in, behaviour centric tests that are not close-coupled to structure, can also be unit tests. And most of the time, it's a better kind of unit test.
Kent Beck said many times: "tests should be coupled to the behavior of code and decoupled from the structure of code."
"test behavior" was the original intent of unit tests. The idea that unit tests are only close-coupled class-method tests, or that testing 2 collaborating classes from the same app at once counts as an "integration test" is a latter-day misconception. A dumbing down.
I read through this book relatively recently and agree with the praise here for the core idea that legacy code is code that is untested. The first few chapters are full of pretty sharp insights that you will nod along to if you've spent a decent amount of time in any large codebase.
However, most of the content in the last half of the book consists of naming and describing what seemed like obvious strategies for refactoring and rewriting code. I would squint at the introduction to a new term, try to parse its definition, look at the code example, and when it clicked I would think "well that just seems like what you would naturally choose to do in that situation, no?" Then the rest of the chapter describing this pattern became redundant.
It didn't occur to me that trying to put the terms themselves to memory would be particularly useful, and so it became a slog to get through all of the content that I'm not sure was worth it. Curious if that was the experience of anyone else.
Thanks. After I wrote it a friend said "I think you just gave people permission to do things that they would've felt bad about otherwise." I think he was right, in a way. On the other hand, not everything is obvious to everyone, and it's been 20 years. Regardless of whether people have read the book, the knowledge of these things as grown since then.
I think of the second half much more as reference. I can give it to a junior engineer or early mid-level and say "here is an example."
It's harder if they can't read the older examples, but I can google for a more modern example as well. It gives nomenclature and examples.
Junior developers in javascript codebases of 7-10 years old will not have the experience necessary in some cases. I am coaching them as a manager trying to introduce a concept, not a professor.
I may be doing a disservice to their long term development at the cost of short term gains. However, I don't think this is true. There are a lot of developers who will never work in a C, C++, C#, or Java codebase. And I try to adhere to Krashen's "comprehensible input" theory as it has a lot of application to learning the language of software development as well.
(See https://www.languagehumanities.org/what-is-the-input-hypothe... )
Why do you have junior developers maintaining codebases older than themselves? ))
I happen to read this book in my early career. I was mid-level. Beyond struggling with codebases, but hadn't yet developed an intuition with codebases. This book blew my mind then. It gave me whole new ways to thinking. I recommend it all the time to people in early career because how to handle a massive legacy codebase isn't obvious at all when you haven't been doing it for a long time.
All the blockquotes are coming in as black on black for me in Safari, Firefox, and Chrome. This appears to be due to a css file called "https://understandlegacycode.com/_astro/ai-support.D3anziw5....". Anyone wanna lay odds on whether that filename is a big tell that much of the text is also written by three autocompletes in a trenchcoat?
Vite/Rollup name assets based on one of the included files, which can lead to funny and misleading file names like this one.
I've replaced a few large legacy systems over the years and I disagree with most of the points mentioned in the link. The only way guaranteed to work is to run the old system concurrently with the new system with live inputs and compare results for a trial period and fixing discrepancies as they arise. Only when there is 100% behavioral/data fidelity with the old system can a switchover to the new system occur.
I'm not aware of the formal Design Pattern name, but a google search yielded this blog post on the subject: https://medium.com/@sahayneeta72/parallel-run-strategy-7ff64...
Coincidentally this is the same strategy github employed when verifying libgit2: https://github.blog/engineering/engineering-principles/move-...
I’ve seen Martin Fowler call something like what you’re describing the Strangler Fig pattern
https://martinfowler.com/bliki/StranglerFigApplication.html
Better still, lots of mini-switchovers. I rolled out a bank’s p&l system for bonds that way. Trading book by trading book, those with simpler instruments first, more complex ones later. We finished ahead of schedule!
You're assuming the "legacy" system is being replaced by a new one, which isn't the scenario being described in the link or the book. They cover approaches for continuing to safely evolve the legacy (i.e. untested) system.
Rewriting the legacy system is one of the valid paths to maintain it. There can be multiple reasons to do that like operational risk which cannot be mitigated, maintenance overhead, risk related to the existing dependencies of the system.
Let me be clear about the situation Mr. Moneybags. You have built a billion-dollar company on top of a giant legacy codebase without any tests.
Now that it's become clear that the thing is about to collapse in on itself, you've brought in Mr. Feelgood Consultingman, to give us engineers generic advice, so that suddenly it's not your fault that this digital superfund site is in the state it is, but your engineers' for not following the consultants advice.
> First, add tests, then do your changes
This can be a superpower.
I once had to replace a PostgreSQL-interfacing layer of a large+complex+important system, and most of the original tests had been lost.
It's the kind of change that could be an existential risk for a company that needs the system to be available and correct.
So I built a comprehensive test suite for the existing PostgreSQL-interfacing layer, tested it, made drop-in compatible API using the new way to talk with PostgreSQL, tested that, and... the entire huge system simply worked with the replacement, without a lot of headache/defects/dataloss/ulcers.
> Before you change code, you should have tests in place. But to put tests in place, you have to change code.
Keep reading. You don't always have to do it in the heroic way the article described in this section. Modularity and backward-compatible interfaces, FTW, when you can. The "Sprout" and "Wrap" techniques that the article describes later.
Also, one complementary general technique that the article didn't get into is that sometimes you can run two implementations in parallel, and check them against each other. There are various ways you can do this, involving which really implementation really takes effect, and what you do if they don't agree. (Related: voting configurations in critical systems.)
> Characterization tests
The test suite not only let me validate the implementation, but the exercise of developing the test suite also helped me understand exactly what I should be implementing in the first place.
Sometimes I had to look at the implementation, to tentatively figure out the semantics, then testing validated that also.
> Use scratch refactoring to get familiar with the code
In reasonable cultures and with reasonable management, or if you don't tell anyone. Otherwise, it's the same kind of risk as the old "throwaway prototype" problem: someone with authority says "looks good; I told the customer/CEO we just need to make these few more changes, and ship it". Or, in popular Agile/Scrum processes, "I thought you already completed the refactor last sprint; why are you doing it again".
This book is extremely overrated because the whole thing can be summed up in two bullet points:
* write your new code somewhere outside the main solution and call it from the old solution
* automated tests are pretty cool and you should write these whenever possible
I found the book to be close to useless when I was working with actual legacy code. How do I write an unit test for an application that has an embedded Visual Basic script support with dozens of scripts that are thousands of lines long? The book does not answer this question at all because the author assumed I have the luxury of working with Java or an another language that supports the object-oriented paradigm and can be endlessly extended with no limitations whatsoever.
>How do I write an unit test for an application that has an embedded Visual Basic script support with dozens of scripts that are thousands of lines long? The book does not answer this question at all because the author assumed I have the luxury of working with Java or an another language that supports the object-oriented paradigm and can be endlessly extended with no limitations whatsoever.
Why does the idea of identifying seams not apply to Visual Basic Script?
I've never worked with Visual Basic Script, but I don't see why Feathers' strategy wouldn't apply.
I agree that modernizing legacy code is easier in languages like Java, but I don't think it's strictly necessary. I've used Feathers' techniques for testing C code.
The code base I work on has multiple layers of wrapper code from people following this sort of advice. Sure, it's safe, but once the code is two layers of wrappers deep, you'll see the downsides.
I feel like there is a need for a new paradigm on navigating code; and reference documentation for that matter.
I like how https://gwern.net and https://en.wikipedia.org allow you to hover over terms and show you a quick glance of a term you might not know, and then you can fan out to create an understanding for the basis needed to understand the material in front of you. I feel like some sort of windowing system where I can pin and move references around and then kinda have the llm explain or reference things might be of use to me, as in help me navigate the unknown. Is there a "study companion" application of the sort?
I find that this is easier to do with a language like Java than say Python, I need as much information as I can in order to understand the decisions that led to the current implementation.
Sometimes when I want to change some piece of legacy code, I need to know the rationale behind the code written here, although keeping the interfaces the same and changing the implementation allows me to go quite far.
The most important part:
> You have to deal with Legacy Code every day.
Legacy code is code you didn't write. It used to be that code you didn't write was written by past team members. These days, we have legacy-code-generators that write code you didn't write at a much higher rate then your company can fire team members.
It's easy to say 'write tests', but it's difficult to do so if you don't know what the actual requirements are.
People often think they are doing it 'properly' now by starting simple, but as they learn more and add functionality, they end up with the same complex mess they wanted to avoid.
Right, but not knowing what tests to write is feedback that your [yet to exist] tests are trying to tell you.
Big caveat that I’ve not read the book but I get that the premise is “legacy code is code that is untested” and I’ve always struggled with that definition. I think a more accepted definition would be that it is not well understood, uses old tooling/languages/runtimes and is usually high stakes code (driving some business that was successful enough to last longer than the staff that coded it up). I’m sure added tests help deal with legacy code under that definition but not sure it’s the panacea, I’ve certainly seen code without tests lots very high coverage that people area afraid to work on due to them being unfamiliar with the domain and codebase.
Love this resource, really looking forward to perusing the full text.
And to echo what others are saying I have spent the last month experiencing for the first time how not simple throwing a meaningful test suite together is for a ginormous legacy codebase. I was glad the author briefly seemed to acknowledge that but still... the pain...
They said the playwright ui was supposed to make it easy... Just plug it into an LLM they said... It should just take a few days right?
No. Run away from any sort of refactor or rewrite. Don't even think about it. Do not proceed. If you're thinking that you can do better, you will be humbled in the worst way. Ignore my warning at your peril. I'll never again for the rest of my life make the horrible mistake of rewriting any system. The article's tactics are all good advice – but it's like tactics for surviving on the front line. You win by never going there in the first place.
I think the riskiest migrations are the ones where migration is done in parallel. Internal org power struggles get leaked, whole teams are lobbying against the effort. And on top of all of that rediscovering many things all over again. That in response to cases where a company might decide that the fix too all legacy -> new system is by throwing more money at the problem.
The only issue I have with writing tests before refactoring is that sometimes it can take a really long time to write those tests and cover all the cases, not to mention needing to sometimes refactor to make the code even testable.
I've made huge successful refactors using nothing but carefulness and manual testing, maybe just a very little bit of unit testing :)
I like to make the distinction that the absence of automated tests is not the absence of tests altogether, and that the time it takes to get an automated test set up might be longer than doing the test manually. This is especially important to be aware of if the tests will be temporary because the code is about to be changed.
Of course the goal is to reach an end state with automated tests, but insisting on 100% automated tests up-front can actually prevent the refactoring from even starting.
I would argue that legacy code has more chance of going along with test code than new code. Often code is written and tests grow during its maintenance.
Another thought... if I'm tasked with maintaining or adding features to existing code, should I feel responsible for writing tests for the existing codebase?
Tests in legacy code... LOL
From my real life experience with legacy code:
- There is usually a "test" folder, but what they test look nothing like the actual code, they often don't even compile, and if they do, they fail, and if they don't, that's because every failing test is disabled.
- Refactoring? What refactoring? Usually, all you see is an ugly hack, usually noticeable because the style is different from the rest of the code base. The old code is generally commented out if it is in the way, left alone as dead code if it isn't.
- Writing tests yourself? It would require you to put the test framework back in order first, they don't have the budget for that. Something as simple as reformatting the function you are working with is already a luxury.
- Sometimes, some refactoring is done, but that's only to add new bugs as to keep things exciting.
Still, as surprising as it may seem, I actually like working with legacy code. It is a challenge, understanding what it is doing (without reading the documentation of course, as if it exists, it is full of lies) and trying to leave it in a better state than it was before in a reasonable amount of time. It is great at teaching you all the antipatterns too, very useful if you end up in a greenfield project later on and you don't want it to end up like all the legacy code you have worked on before. If people actually use it, it will, but you can at least delay the inevitable.
> Another thought... if I'm tasked with maintaining or adding features to existing code, should I feel responsible for writing tests for the existing codebase?
Do you trust yourself enough to not break existing code while maintaining or adding features to it? What would be the consequence of you screwing up? Where would your screw up get noticed? Is it a scary person or group of people who will chase you down to fix it?
I've worked long enough to not trust myself at all anymore, regardless if it's old code or new. Then I evaluate according to above. Usually I land firmly in "yeah, better test it"-territory.
The goal of existing and new functionality is reliability.
What you touch will be on you. So writing a test for your own things, and testing what you are using of the legacy code as you go is a good way to maintain your own coverage in case someone else breaks something in the legacy code, or maybe an update to a library or something goes sideways.
Since you'll be doing a good job of mapping it out below is something elsee. The nice thing is LLMs can help a lot with writing tests.
Reliability can be achieved in a number of ways.
Where I've come across an unknown spreadsheet gone wild, or a code base who's jedi knights have long since vacated, I try to get a sense of putting together the story of how the project started and how it got to where it is today.
If I was cold, I'd first focus on the most critical parts, the most complex, and most unknown potentially to put testing around first.
If refactoring was a goal, for me that means it has to run the same as the old code. One way to do that is see if the existing code can become a service that can be compared to the new service.
LLMs have been really fascinating for me to apply in this regards because I've had to map and tear apart so many processes, systems, integrations and varying interpretations and memories.
AI can even explain what most code is doing no matter how convoluted it is. From there, things like test driven development, or test driven legacy code stabilization is much more doable and beneficial not just for the legacy code, but keeping the AI behaving if it's helping with coding.
>Another thought... if I'm tasked with maintaining or adding features to existing code, should I feel responsible for writing tests for the existing codebase?
Write tests for new additions to the code, when making major overhauls to sections of it, or when a bug is discovered that the old tests did not catch.
Those are the 3 cases I would say you should add a test. #3 is most important, in my experience.
This book talks about unit tests, but for UI they are mostly useless. I found that for UI the most essential refactoring tools are storybook and visual diff tests.
I remember the time when we had to delete “a lot” of UI tests because the implementation and the framework deprecated and we had to move forward (usual stuff, eg vulnerabilities). Refactoring all of those tests would require a bunch of effort therefore we stopped adding new features and just waited for the last customer subscription to expire, then we moved to other more important stuff.
Appreciate the intro to the book.
I recently talk therapied some legacy code through Claude Code back to life, but along the way put some frameworks in place for the codebase itself, and overall with how I think about approaching existing implementations, which helped a ton to shed a path forward for modernization.
It ultimately reminded me there's always a ton more to learn and think about, and it's sometimes quickest to learn from others experiences when considering paths forward, so the book is a helpful share, thanks.
All code is eventually legacy code in one way or another, whether it's the code directly, or the infrastructure level. Today's code might be the best one writes today.. looking back in 5-10 years.. one might wonder if best practice was best practice.
This reads like a blog written by someone who sells expensive consulting for business critical issues, but not to actually solve them, but dispense Eastern Wisdom to the poor developers facing and impossible and unsavory task. This sounds like this was written by a guy who was never directly responsible for producing actually usable and productive results.
This is done so management can lay back and say they already did their due diligence, now you know how to do it, now off to the mines! And be ready by the end of next week!
First:
If your codebase doesn't come with tests you are fucked. There's no possible way you can refactor anything without angry customers calling next day you broke their use case. I worked on legacy code that did come with tests (or even better, well written docs!) And even then it was basically everyday that we broke some elaborate use case checked by the tests.
Management will never approve of a refactor, and with good reason.
> unit tests are fast and reliable
They are also often worthless, because they don't capture real world behavior. Not always but having to mock out half your codebase (including libraries you couldn't possibly know how they work, like a legacy version of Qt your app depends on). You end up with five hundred lines of mock for ten lines of test and it doesn't even give you confidence in anything. These workshy consulting ghouls often force devs to write unit tests, who full well know they're going to be absolutely worthless.
Because you have no idea how it's supposed to work.
> Don’t make your code depend on libraries’ implementation
Good advice , though isn't the definition of legacy code that its already written and after refactor it should keep working like it already did? If somebody before you pulled in a COM object from Microsoft Excel 2003, and your ERP system pivotal to your companies success relies on the exact behavior of that component, where does that leave you?
Maybe the technical aspects of the book are okay.
However, the big problem with legacy code is always political. And the only book I've seen ever try to address that is "Kill It with Fire".
It's one of the few books that talks about the need to keep your team motivated and plugged into the political system given that they are working on the thing that's super important but also almost invisible. You need to be constantly selling what is going on in front of the important eyeballs.
Unfortunately, a lot of the anecdotes have an undercurrent of "Until the system has actively exploded into a million pieces such that somebody with real power has their ass on the line, don't bother."
the website doesnt render properly on mobile. the first aid website is unreadable on mobile darkmode
Interesting article, but a small issue - I can’t read this properly on my iPhone as it doesn’t fit on the screen!
What I’ve found:
- Anything with millennial-looking cartoon characters in cartoons is bad.
- Anything with furry characters is good.
The pull quotes are in black on a black background for me on Brave, made it a bit of a confusing read I have to say!
I could read it once I forced my browser into light mode.
Same on an iPad Air in Safari
What sort of LLM/Copilot advice file could you write to encapsulate all the good advice here? Would "approach this problem using the ideas from Michael Feather's book Working Effectively With Legacy Code" work?