6 ms·

The key points of "Working Effectively with Legacy Code"

182 points by lordleft 1y ago

allemagne 1y ago
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.
- ebiester 1y ago
  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.
  - dotancohen 1y ago
    > 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.
    - ebiester 1y ago
      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-hypothesis.htm https://www.languagehumanities.org/what-is-the-input-hypothe... )
      - dotancohen 1y ago
        Why do you have junior developers maintaining codebases older than themselves? ))
- michaelfeathers 1y ago
  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.
- iteria 1y ago
  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.
pmg101 1y ago
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!
- antonvs 1y ago
  Same on an iPad Air in Safari
- sam_bishop 1y ago
  I could read it once I forced my browser into light mode.
nuancebydefault 1y ago
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?
- j45 1y ago
  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.
- ZaoLahma 1y ago
  > 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.
j45 1y ago
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.
umbula 1y ago
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?
chris_wot 1y ago
Interesting article, but a small issue - I can’t read this properly on my iPhone as it doesn’t fit on the screen!
commandlinefan 1y ago
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".
- PaulHoule 1y ago
  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.
  - tome 1y ago
    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.
- _mu 1y ago
  > 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 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.
- zabil 1y ago
  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.
egypturnash 1y ago
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.css 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?
- KTibow 1y ago
  Vite/Rollup name assets based on one of the included files, which can lead to funny and misleading file names like this one.
Lovesong 1y ago
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.
- bitwize 1y ago
  > VB.NET *laughs in VBA*
  - jaggederest 1y ago
    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)
- th0ma5 1y ago
  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.
jbjbjbjb 1y ago
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.
nitwit005 1y ago
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.
fknmillenisla 1y ago
What I’ve found: - Anything with millennial-looking cartoon characters in cartoons is bad. - Anything with furry characters is good.
avgcodor 1y ago
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-7ff64078d864 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-fast/#preparing-for-an-experiment https://github.blog/engineering/engineering-principles/move-...
- grahamplace 1y ago
  I’ve seen Martin Fowler call something like what you’re describing the Strangler Fig pattern https://martinfowler.com/bliki/StranglerFigApplication.html https://martinfowler.com/bliki/StranglerFigApplication.html
- asplake 1y ago
  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!
- sciurus 1y ago
  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.
  - sublimefire 1y ago
    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.
neilv 1y ago
> 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".
fogzen 1y ago
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.
bsder 1y ago
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."
guardian5x 1y ago
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.
- yakshaving_jgt 1y ago
  Right, but not knowing what tests to write is feedback that your [yet to exist] tests are trying to tell you.
pkdpic 1y ago
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?
internet_points 1y ago
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.
brainzap 1y ago
the website doesnt render properly on mobile. the first aid website is unreadable on mobile darkmode
shahindohan 1y ago
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 :)
- jt2190 1y ago
  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.
gnulinux996 1y ago
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 https://gwern.net and https://en.wikipedia.org 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.
sesm 1y ago
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.
- sublimefire 1y ago
  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.
ManlyBread 1y ago
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.
- mtlynch 1y ago
  >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.
  - ManlyBread 1y ago
    >Why does the idea of identifying seams not apply to Visual Basic Script? Because the script is embedded and requires the runtime of that proprietary legacy application and there's no way to make it run outside that runtime. Think of it as trying to add unit tests to Excel macros.
adonese 1y ago
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.
torginus 1y ago
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?
torginus 1y ago
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.

182 points by lordleft 1y ago

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.

ebiester 1y ago
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.
- dotancohen 1y ago
  > 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.
  - ebiester 1y ago
    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-hypothesis.htm https://www.languagehumanities.org/what-is-the-input-hypothe... )
    - dotancohen 1y ago
      Why do you have junior developers maintaining codebases older than themselves? ))
michaelfeathers 1y ago
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.
iteria 1y ago
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.

pmg101 1y ago

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!

antonvs 1y ago
Same on an iPad Air in Safari
sam_bishop 1y ago
I could read it once I forced my browser into light mode.

nuancebydefault 1y ago

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?

j45 1y ago
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.
ZaoLahma 1y ago
> 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.

j45 1y ago

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.

umbula 1y ago

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?

chris_wot 1y ago

Interesting article, but a small issue - I can’t read this properly on my iPhone as it doesn’t fit on the screen!

commandlinefan 1y ago

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".

PaulHoule 1y ago
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.
- tome 1y ago
  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.
_mu 1y ago
> 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 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.
zabil 1y ago
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.

egypturnash 1y ago

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.css 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?

KTibow 1y ago
Vite/Rollup name assets based on one of the included files, which can lead to funny and misleading file names like this one.

Lovesong 1y ago

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.

bitwize 1y ago
> VB.NET *laughs in VBA*
- jaggederest 1y ago
  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)
th0ma5 1y ago
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.

jbjbjbjb 1y ago

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.

nitwit005 1y ago

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.

fknmillenisla 1y ago

What I’ve found: - Anything with millennial-looking cartoon characters in cartoons is bad. - Anything with furry characters is good.

avgcodor 1y ago

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-7ff64078d864 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-fast/#preparing-for-an-experiment https://github.blog/engineering/engineering-principles/move-...

grahamplace 1y ago
I’ve seen Martin Fowler call something like what you’re describing the Strangler Fig pattern https://martinfowler.com/bliki/StranglerFigApplication.html https://martinfowler.com/bliki/StranglerFigApplication.html
asplake 1y ago
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!
sciurus 1y ago
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.
- sublimefire 1y ago
  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.

neilv 1y ago

> 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".

fogzen 1y ago

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.

bsder 1y ago

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."

guardian5x 1y ago

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.

yakshaving_jgt 1y ago
Right, but not knowing what tests to write is feedback that your [yet to exist] tests are trying to tell you.

pkdpic 1y ago

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?

internet_points 1y ago

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.

brainzap 1y ago

the website doesnt render properly on mobile. the first aid website is unreadable on mobile darkmode

shahindohan 1y ago

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 :)

jt2190 1y ago
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.

gnulinux996 1y ago

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 https://gwern.net and https://en.wikipedia.org 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.

sesm 1y ago

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.

sublimefire 1y ago
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.

ManlyBread 1y ago

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.

mtlynch 1y ago
>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.
- ManlyBread 1y ago
  >Why does the idea of identifying seams not apply to Visual Basic Script? Because the script is embedded and requires the runtime of that proprietary legacy application and there's no way to make it run outside that runtime. Think of it as trying to add unit tests to Excel macros.

adonese 1y ago

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.

torginus 1y ago

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?

torginus 1y ago

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.