Loving Legacy Code with Jonathan Boccara

Meet Our Guest, Jonathan Boccara

Jonathan Boccara: So I get to talk with quite a few people. And what I learned from that is that legacy code is everywhere. I don’t think I’ve met anyone who doesn’t have to deal with legacy code in a substantial portion of his work, at least.

Adam: Hello and welcome to CoRecursive. I’m Adam.

Don: I’m Don. That was Jonathan Boccara.

Adam: He’s a French C++ developer and he’s on a mission to teach people how to work more effectively with legacy code so much so that he’s written a book all about it.

Jonathan Boccara: I hope this book will change how people will see that everyday life with working with existing code.

Don: To write the book, Jonathan needed to define what legacy code was.

Jonathan Boccara: It’s essentially existing code, that’s hard to work with. I had to come up with a more precise definition. So my definition would be threefold. First it’s code that’s hard to understand for you. Second it’s code that you’re not comfortable changing and three, it’s code that you’re somehow concerned with.

The Reason Why Legacy Code Is Hard to Work With

Adam: So today we want to answer this question. How do you get good at working with large existing code bases? How do you work with legacy code basically?

Don: And how do you enjoy working with legacy code bases?

Adam: We’re going to talk about what legacy code is, how to work with it, how to improve it, when you shouldn’t improve it and as you said, why you should want to enjoy working with.

Don: Yeah. Legacy code is after all just code and reading code and understanding it is what our job is all about.

Adam: Yeah. There’s this quote from Joel Spolsky, about legacy code. The reason that developers think that old code is a mess is because of a cardinal fundamental law programming. It’s harder to read code than it is to write it. Nobody talks about that, right? It’s totally true. Writing code is easier than reading it. That’s weird, right? It’s the opposite of what you would expect.

Don: It’s very counterintuitive.

Adam: Yeah. So today we’re going to explain how to live with and love the legacy code that you have to work with and how to think about code you’re not familiar with in general. How to get comfortable with it. And to do that, I took my various questions about legacy codes to Jonathan.

Don: Yeah. His process is to accept the code, critique it, own it, document it and improve it.

Adam: And we’re going to take you through all the stages. Let’s start at the beginning.

Accepting the Code

Jonathan Boccara: I’ve been a software developers for couple of years now. And eight years, I noticed that people around me, the people I met like meetup or on the internet or wherever they were sad about the code they were working with. And I think it’s a terrible thing because most of us, we choose our job out of passion. Quite a few developers have been programming before they were actually working as a developer.

And it really saddens me when I see people’s motivational wither over time, because it’s not what they were expecting and that don’t really know what to do with it. And they feel like they’re a victim of code and the food log that ended up in the worst place on earth. When you think about it, when you get into a new job, it’s like your first job or something, you’re probably going to get into an existing project.

And perhaps this project or company has been there for years and some other people have worked on it, perhaps quite a lot of other people. And so on your first day, you’re going to be thrown into that huge sea of code written by perhaps thousands or more of people over years. So you have to be able to work with that somehow. When you enter a company, chances are, you’re going to have to face them go. That’s not as easy to work with as you would wish it were. So, yeah. That’s an essential thing because that’s what’s out there and you have to do something with it.

Don: So I would call this acceptance. Accept that as a professional, you need to deal with old possibly crappy code.

Adam: Yeah. Google has tons of old C++ code. Facebook has tons of old PHP code. Somebody’s maintaining old versions of windows and just being old or not being in your favorite language, doesn’t mean that it’s not valuable code.

Don: I feel like this is honestly the hardest part, accepting old crappy code and having to work with it.

Adam: Definitely agree. All right. Next up in Johnathan’s steps is critiquing.

How to Critique Legacy Code

Jonathan Boccara: When you look at a piece of codes that you have written a while ago or that someone else has written, something that’s not fresh for you, it happens that it doesn’t look quite right to you. It feels like it’s badly written. And when you see that, you have two choices I think. One of them is saying, this is bad code and move on. And the second choice is to try to express why this is bad code, because it happens that you know this piece of code is not well designed, but you can’t quite place a finger about on what exactly is wrong with it. And sometimes it takes a bit of time of reflection and analysis to exactly pinpoint what’s wrong with that piece of code. And being able to critique this code in depth, being able to voice exactly in excruciating details why you didn’t like it, once you find that when you identify what’s wrong with it, you know what to pay attention to.

That specific aspect of design, it’s important because it made you feel uncomfortable in the first place. And next time you’re going to write your own code, then you’re no need to pay attention to that. By doing this kind of analysis, you get better as a programmer. I often compare that with a vaccine. When you get a shot of a disease, but that’s not dangerous, and your body has time to do it’s stuff for the immune system with antibodies or whatever. And then your body remembers it. It remembers exactly what’s wrong with that molecule or whatever. If you happen to actually encounter the actual disease, then your body is going to recognize it and smash it apart in no time.

Don: I really like this metaphor. Don’t just say, “Oh, this code is horrible.” Understand why it is bad.

Adam: Yeah. If you want to be a great developer, you should actually work on some legacy code. There is one caveat with this critiquing approach though.

Jonathan Boccara: Yeah. I was going to say it’s also a dangerous thing to do to critique or rather to criticize codes. As a natural reaction, people think existing code that the fear is badly designed. And sometimes it’s badly designed. Sometimes it’s not badly designed and it’s more difficult than it looks, but it’s not really the point. An important message I’m trying to get across is that you should not complain if you don’t intend to improve the code. So you don’t criticize just for the sake of it, because it’s a natural thing to do. And if you start by saying, “Oh, this code is terrible. Oh, I would have done such a better job.” and you do that all day, then you’re going to get depressed and you’re going to depress everyone who sits around you. So I think you need to be careful to criticize only for learning purposes or improving the code.

Adam: That’s the tricky part. It’s really easy to complain about code that you have to work with. It just comes naturally, right? When you see some code, you’re like, this is a mess and it can actually be hurtful because the person who wrote it might be sitting nearby.

Don: And also, you don’t understand the original constraints. Maybe this code made sense at some point, maybe it still does and it’s just so complicated that you don’t know how it’s supposed to work. I think that what Jonathan is trying to say is if you can try and move past that and maybe accept it, then you can better yourself.

Taking Ownership of the Code Can Be Empowering

Jonathan Boccara: If you have to work with codes, be it good, be it bad, be it the one you wrote or be it the one that someone has wrote, think about sets as your code. If you’re working on it, this is your code. You have to take ownership. And even if you don’t think it’s good, even if you didn’t write it yourself, this is your code. And when you get into that mindset, you have the position as a leader. You feel empowered to do things with these codes because this is your code. So, it doesn’t matter that it’s bad. You have to make the most of it.

And when you take the ownership over the code you’re working on, you’ll leave this victim attitude [inaudible 00:00:09:06]. That’s one thing that’s particularly frustrating with legacy code is when you feel like you’re bearing the consequences of someone who made a poor design in the past. And it’s not true, because in the first place, maybe that person didn’t make a poor design. Maybe you’re just not seeing the big picture. And maybe even in the same situation, you wouldn’t have done such a better job.

Adam: This is such a great attitude. I’ve been accidentally on the receiving end of like, what moron wrote this code and it’s not fun.

Don: Yeah, ownership is a great attitude. And also I think what you’re talking about is empathy. You might have some empathy for the person that wrote it.

Adam: Okay. So far we have accepted our code. We’ve learned how to critique our code and take ownership over the code.

Don: And don’t be a dick.

Adam: You mean develop empathy, maybe?

Don: Yes. And develop empathy and don’t be a dick.

Considerations for Valid Code Critique

Adam: All right. Before we leave critiquing, Jonathan has a rule for what type of code critiques he considers valid.

Jonathan Boccara: Oh, that would be any critique that’s technical. One thing that comes up very often is levels of obstruction. If I had to sum up best practices in three words, that would be those levels of obstruction. That’s something that’s sometimes not respected and that makes the code look bad and complicated.

Adam: Do you have an example of that?

Jonathan Boccara: Yeah. We have to choose a name of a parameter or anything else, really, but let’s stick to the parameters example. That’s a tricky thing to do. Naming is a difficult thing to get right in programming, surprisingly. I think that to get the right name, you have to choose the name that’s adds the right level of obstruction. And to do that in practice, you have to think about what this object you’re trying to name represents. It may sound a bit trivial, but this question, what is this object representing?

I think it’s the crux of how to do good naming. Example of the parameter, if you name your parameter with a name that reflects how it participates to the inside of the function, but then you’re too low in terms of levels of attraction because the parameter represents something that’s at the same level as the name of the function. And if it looks like something that’s difficult to implement a function, then it’s too low. And on the other hand, if you’re too high in terms of level of obstruction for a parameter, that would be that your parameter is bound to the context that uses that function. Does this makes sense?

Adam: I think I understand if I have some function that is called, let’s say format email. And it takes them a string and it goes through and it removes any double line breaks, right? And I call it that because I use it to format my email. So that is a violation of this levels, right? Because it doesn’t actually format an email. I’m giving it too specific of a name. While it’s actually should be called to something like remove extra line breaks.

Jonathan Boccara: Exactly. And your parameters shouldn’t be called email, but it should be called texts for example. And that’s a great example because it shows immediately.

Don: If you’re keeping track, we have now covered accepting, critiquing.

Adam: And also, using that critique to improve your code.

Don’t Fix Code Right Away

Don: And speaking of fixing of the code, should I just fix these right away when I find them?

Jonathan Boccara: Oh, no, absolutely not. I don’t think so. The thing is it would be great in theory if you could fix the world, that would be awesome. But the thing is legacy code base tend to be advanced. One thing that makes codes go into legacy codes is age. If you have old code, it has more chances to be legacy than brand new code, you just ship. But I’m sure that all the code is not equal. And that really shows at any scale, even if you’d add function, you’re going to see that all lines don’t matter, but just a handful of lines that really contain some meaningful action. And I think that’s true for larger scales, code based or some places where you go all the time. Everyone goes there all the time. That’s the places that are hot if I may say in terms of cash for Cadbury.

It’s the places that people change. They make fixes because our bugs will be called out interesting and the clients want more features in them. And those parts, they represent a portion of your copays. And this is the portion that matter. The point of code is to make a piece of software run and to make it run in a way that will make customers happy. And that’s a very harsh business view, but I think that’s what code is for in a professional context, of course. So making good codes has to somehow impure improve your business.

So if you make code better, it can be because better code tends to have less bugs, all right? Or because it’s easier to add features to better code that it needs to code that you can’t make any sense of. For example, you shouldn’t do a refactoring project just because it’s easy to do. Or just because it doesn’t cost a lot. And I hear people sometimes say, Oh, I’m going to go in that code and improve. I don’t know, the names or make the code cleaner. And that’s an easy thing to do. And if no one goes through that code, that doesn’t matter. It’s the same thing as fixing some other’s company codes that will make your business better.

Adam: You’re saying the cost is low, but the value is zero.

Jonathan Boccara: Absolutely. That’s exactly my point. No, I’m not saying that naming is a bad thing, that naming is tremendously important. But that matters more in code that matters.

Adam: So my biggest concern is not what Jonathan just described, fixing code that doesn’t need to be fixed. It’s actually just making code worse, by trying to improve it. So I asked Jonathan how to deal with that situation.

Making Code Worse By Avoiding Nesting

Jonathan Boccara: I think you can do the same kind of analysis, when you did choose to fix a piece of code, to improve its quality by making a refactoring task after it. I think it’s a great thing not to move on immediately, but rather to think about why it’s better. And once again, it’s not something that’s obvious to do sometimes. For example, I remember one time where we had a slightly complicated if statements, something that was an if involving several billions and a bit of nesting. Nothing monstrous but the thing that takes you a few minutes to figure out.

And we were thinking, well, if we see it often, maybe we should do something about it. So we went about and refactored it and we moved it around and somehow it was looking much better, much easier to understand. And then we stopped and thought, why is that? Why is it better? It looks better, I feel I can understand it better and that’s the point of code really. But why is that? And after a few minutes, I hope so. Perhaps in more, I don’t remember, maybe an hour of analysis or perhaps when you sleep on it really, we realized it was better because it was sticking to the specification.

The business had explained to us if such and such condition [inaudible 00:17:26] within this context and without this other, then we should do that thing. And after the refactoring, our if statement was looking exactly like that. And surprisingly, it was more nested. By nested I mean, when there’s an if statement inside of an if statement and you can measure nesting with the indentation, which is the distance from the left margin of just your screen.

And there’s this general guideline about if statement that’s classical thing in programming, which is avoid nesting. Refactor your if statement so that they are as literal, nested as possible, if it can be not nested at all. And in this particular case, the if statement became more nested but clearer. And that was because it stuck better to the specification. So we came up with that good line that we try to use every time we have to do something that’s related to a conditional, try to stick to the specification, to what the business said, more than about nesting.

Adam: I like Jonathan’s example, the structural indenting. So following the rule very clearly about reducing indent actually would lead you to a solution that was less good than what you ended up with.

Jonathan Boccara: Exactly.

Adam: It’s not, totally rule-based but you should be able to explain it somehow.

Jonathan Boccara: Yeah, absolutely. You have to know the rules. You have to know that nesting is something that can be dangerous. That’s a smell, but performing your analysis on your codes allows you to go further, expand beyond the rules. And that’s another level of skills.

Create Understanding With Documentation

Don: Learn the rules for improving code but learn the exceptions. All right, we have hit accept it, critique it and improve it.

Adam: And there is one more key left to legacy code. And this one I have to admit is not my favorite. That is documentation. To Jonathan, the magic of documentation is…

Jonathan Boccara: You can create understanding out of nowhere with documentation. That’s very surprising thing to do because it sounds like magic. But the very facts of explaining what you already understood, helps you understand more. You probably know that if you have made a talk or written a blog post or written a book or written actually a piece of recommendation, if you explain anything to anyone in any form, and I’m sure every listener did at some point, you know that this made you realize things. And if anything else, it helped you realize that there were things you didn’t know. There were holes in your understanding, and that gives you more questions to answer. To make it consistent whole. So that’s just one aspect of how documenting helps understanding. Now-

Adam: Yeah. That’s a great example because you’re saying that the actual act of explaining it to somebody via documentation actually deepens your understanding. It’s a way for you to understand it better.

Jonathan Boccara: Yeah. And of course it goes without saying that it helps the other people [inaudible 00:20:54] go with that, we’re going to read your documentation. Now, I think… Yeah, when you’re a software developer doing management documentation is not hype. That’s not the thing that motivates people becoming developers, or at least most people I’ve met. That’s why I think it’s important to realize how important it is and that it’s not a terrible thing to do. And one way to see things that I’ve realized over time by actually managing people and making them right documentation is, documentation, just like improving good quality, you don’t do it because it’s a good thing. You don’t do it because you are a good person. You do it because it helps the business. And knowing that you’re going to quit this horrible for everyone attitude where you write documentation.

Now we do homework. Like, my manager asked me to do that, I don’t have a choice. I’m going to crank it out and be done with it. And that’s the worst documentation you can make for you and for everyone. For you, because it’s going to be pain. And for everyone, because it shows really when you read a piece of documentation that’s been written about someone that didn’t want to write it. That just cranked it out. It shows, and you don’t really understand and it’s not helpful. And if it’s not helpful, then you wasted your time.

How Your Future Self Will Benefit From Documentation

Adam: Yeah. That’s a great attitude.

Jonathan Boccara: Yeah. So, one simple tip I was going to say, when you write documentation is to write it not because you have to, because you’ve been asked to. Or because you feel guilty not to, but write it to explain something you had a hard time understanding, explain it to your past self because you know how it feels not to understand that thing. What’s easy to understand, the tricky parts and it sounded like you were speaking yet to your past self because other people are like your past self. They don’t know about it. And actually your future self has a high chance to be like your past self at some points regarding this particular topic.

Don: In other words, document things because you’re going to forget them and you’re going to need to explain to your future self when you come back to this code, inevitably what it does.

Adam: Yeah. You’re going to be the person reading this documentation. So if you don’t write, you’re just hurting yourself. So we understand now how to work with legacy code. We have accepted, critique it.

Don: Critique it nicely.

Adam: Improve it.

Don: But don’t make it worse.

Adam: And document it. There’s one item from the beginning we haven’t covered though. And that’s how to enjoy working with existing code bases. The key to loving maintenance programming is understanding how valuable of a skill you’re developing. Get good at it, master it, enjoy it. Or as Jonathan says…

Jonathan Boccara: It’s a fascinating thing to be programming with. Love that, but more importantly, it empowers you to do great things and you can do fantastic things with legacy codes.

Don: You can find out more about Jonathan and his book at corecursive.com.

Adam: This interview with Jonathan originally aired on SE Radio, Software Engineering Radio. It’s a great podcast. I’m one of the hosts. Let us know what you think of this show. I’m Adam Gordon Bell.

Don: I am Don McKay.

Adam: Until next time, thank you for listening.

Don: Do you have to do something special to make this work?

Adam: Other way.

Don: Oh, it’s inverted? Why is everything backwards with Macintosh?