In all cases, you need to be able to read code quickly. The more expressive, the easier to read. The less expressive… well here are some heuristics that should help you figure out what a piece of code is doing, in particular the code of a function. Even if that function looks like it doesn’t want you to understand it.

Reading code is like reading a book

How to read a book? If it’s a fiction book, chances are you’re reading it to have a good time. In this case reading it line by line, cover to cover, is what makes the most sense.

But in the case of non-fiction books, you’re reading to acquire knowledge and understanding. And as explained in the classic How to read a book, you never ever want to read them cover to cover. Rather, you want to run an “inspectional reading” first, to achieve two things:

• decide whether this book is indeed relevant for you,
• get an idea of the main message and parts of the book.

An inspectional reading consists in skimming through the book, looking for places that sum up the information (table of contents, beginning and end of chapters, main messages…). And inspectional reading is fast.

Going back to source code, what sort of book do you think source code relates the most: fiction, or non-fiction?

Unless you’re fond enough of a piece of code to enjoy its reading like you would a good novel, source code is read for knowledge and understanding. Like non-fiction books. For this reason, you don’t want to start by reading a function “cover to cover”, that is to understand its code line after line starting from the first and going to the last.

Instead, you want to skim through lines of code, looking for the main information. You want to perform an inspectional reading on code for the same two reasons as for a book:

• deciding whether this piece is code is relevant for you and deserves a deeper analysis,
• getting a general idea of its meaning before getting into the details.

Now how to extract the relevant information during the inspectional reading of a function?

A function is like a story: get spoiled

Before delving into its implementation, the first thing to look at a function is its name. If it’s well named, it should give a general meaning and orient you for what to look for when you inspect the body.

Or better yet, the name, parameters and return type should be enough together to indicate everything you need to know about this function.

The main character dies at the end

However, not all functions are created equal, and some of them require you to get a peek under the hood. Or sometimes, it feels more like a descent in a cave. Or a propulsion into a black hole, in the worst cases.

When you’re inside the cave, what should you start looking for? The first thing to look inside a function is what it returns. All the rest of the function is oriented towards returning that value, because it’s the point of that function.

So get a big spoiler, skip to the end of the function’s story, and start from the last line. It should look like return something. In this case, something is one of the main characters of the function.

Some functions have multiple return statements. If that’s the case, look at all of them, and try to see what they have in common, to get a feel for what that function is returning. Unfortunately, even if functions should return their outputs via their return type, some functions modify their parameters, so that counts as “returns” too.

Since anything can happen in a black hole, some functions go as far as modifying global variables, which also count as output then. And let’s not talk about the functions that return values via exceptions because that’s a whole other dimension.

Anyway, however unfortunate the form the of the output, this is what you should be looking for first if there is one.

Locating main characters and secondary characters

In a traditional plot, the main character is helped by secondary characters to achieve its quest. It is the same in code: a function has intermediary objects, that are not returned from the function but play a key role in its implementation.

Main characters and secondary characters have something in common: you get to see them often. So to know what the function is about, note the objects that appear the most frequently in its code. The function is probably about them.

This technique is also useful if you’re only inspecting a portion of a larger function. If nothing gets returned in that portion, finding the objects that appear the most often helps identity what that portion of code is about.

Skip to the action

Once you’ve located the main and secondary objects of the function, the next thing you want to know is what’s happening to them.

In a function, not all lines are the main action, sometimes far from that. Some lines are merely secondary quests, like getting a value, logging a piece of information, or preparing a secondary character. You don’t want to dwell on those details when inspecting the function. Instead, you want to skip to the main action first.

To locate the main action, you can quickly scan every line of the function, and determine if it looks like the main action, even if with a gut feeling. The point it to do this check really fast. And if it doesn’t feel like the main action, don’t dwell on it, even if you don’t understand all it does. It will become clearer later.

In some cases, you’ll reach the end of the function without having found the main action, because it didn’t looked like it. In this case, make a second pass with the same technique. Now that you’ve considered every line of the function, even if at a glance, the main action should stand out better than the first time.

Identifying the main action may be slow at the beginning. But the scanning of each line becomes much faster and more reliable with practice. With time, your eyes will scan blocks of code rather than individual lines.

This is particularly true if you work on the same codebase for a period of time, because you get used to its style. The coding style of the main action doesn’t look like the coding style of the other bookkeeping stuff of the function.

So what is that function about?

When you perform an inspectional reading first, understanding what a function does becomes like a little game. Find what objects the function revolves around, and what happens to them by filtering out the secondary causes.

This should increase your code reading speed, allow you to read more code, and make it easier to work with legacy code.

Do you have other techniques to understand a function, or code in general? If you do, or if you try the technique presented here, please leave a comment to let us know how it went!

You may also like

• 10 Techniques That Will Make You Understand Other People’s Code Better

The post How to Quickly Understand the Code of a Function appeared first on Fluent C++.

0) Don’t start by looking at the code
1) Reproduce the bug
2) Do differential testing
__2a) Start with a tiny difference
__2b) Continue with larger differences
3) Formulate hypotheses and check them in the code

As laying out the method can look a little abstract, we’re going to go through a case study where we identify the cause of a bug in a concrete example.

It’s inspired from a bug that I’ve seen once in an application. I’ve simplified the domain and the environment to present it more synthetically, but the mechanics of the bug is all there.

So here’s the story: you’re a software developer working for the International School of Harmonica, which is a thriving establishment that delivers harmonica lessons to people around the world, that want to be able to master the subtleties of this musical instrument.

As a hat tip to some of my C++ blogging buddies, we’ll say that the International School of Harmonica has sites in

• Hamburg, Germany
• Aachen, Germany
• Rottenburg, Germany
• Edinburgh, Scotland
• Cracow, Poland
• and Paris, France

Seems that a lot of folks in Germany like to play the harmonica then.

As a software developer for the International School of Harmonica, you have to maintain a large system that tracks what’s going on in the school. And one day, you get a bug report. It’s in the module that deals with lessons subscriptions.

Let’s see how that feature works (it’s simple) and the bug report. Then we’ll apply the above method to find the source of the bug as quickly as possible.

Lessons subscriptions

When a student subscribes for harmonica lessons, the school inserts a subscription via a form in the system. The form looks like this:

It contains the name of the student, the name of the school (which we’ll identify with its city for simplicity here), and a button “Lesson dates…” that leads to the calendar of lessons that this student is subscribed to. Let’s click on that “Lesson date…” button. We see the following screen open:

The left hand side of this screen is taken up by the lesson schedule: these are the dates where the student is supposed to show up and learn how to express a myriad of emotions with their harmonica for an incredibly intense hour. For simplicity we leave out the time in the day of the lessons here.

The user can fill out the schedule manually, or they can use the right hand side of the screen to generate dates automatically:

For simplicity’s sake we assume that lessons are always weekly. Note that the 7th of April is Good Friday in Germany in 2034, but since the configuration of the right hand side of the screen says that a lesson falling on a public holiday should be held the “day before” instead, the second date is the 6th of April.

That’s it for the feature. Let’s now have a look at that bug report.

The bug report

The bug report goes like this:

When we duplicate an existing lesson subscription and select another school of the newly created subscription, we observe that the lesson dates disappear.

But we expect the duplicate to make a carbon copy of the subscription, which means also copying the dates.

Note that if we only duplicate the subscription without changing the country, then the lesson dates remain.

Let’s now apply the above method to find the source of that bug without trudging with pain into the code.

Let’s find the source of that bug, quickly

As a reminder, the method we’ll follow is this:

0) Don’t start by looking at the code
1) Reproduce the bug
2) Do differential testing
__2a) Start with a tiny difference
__2b) Continue with larger differences
3) Formulate hypotheses and check them in the code

Step #0: Don’t start by looking at the code

Let’s go ahead and do 0) Don’t start by looking at the code.

That’s the easiest one, we don’t do anything. Ok, done.

Now let’s do 1) Reproduce the bug.

Step #1: Reproduce the bug

The test case contains a lesson subscription, let’s see what’s in it:

And the lessons dates look like this:

Those are entered manually and don’t use the automatic generation.

Now we duplicate the subscription (say there is a UI action to perform that), give the duplicate a new name and change its country:

Let’s now open the dates:

The dates are gone! Excellent, we reproduce the issue. At this point, we can rejoice since the rest is only a matter of time.

Indeed, this is really a great position because things get harder when you don’t reproduce the issue. Indeed, so many kind of things can have gone wrong in that case (configuration of your dev environment, wrong version in the version control system, misunderstanding of the test case, the test case can only be reproduced once in a given environment and you need to find a backup of the DB to restore… lovely stuff).

Let’s assume that the issue is confined now. Let’s hunt it down with 2) Do differential testing.

Step #2: Perform differential testing

The bug report says that the issue happened when duplicating the lesson subscription. Is it specific to duplicates, or can it happen by simply inserting a subscription from scratch? The only way to know is to test it.

So let’s insert a new subscription:

Let’s fill out some dates:

Now let’s go back and change the country:

And reopen he dates:

Gone.

So the issue has in fact nothing to do with the duplication. This is important because it represents a whole chunk of code we won’t have to look at, because we’re now pretty sure it doesn’t contain the source of the issue. Had we started with the code we may have debugged the duplication, which would have been a complete waste of time. Hence the interest of Step #0 above.

To be even more sure, we can try to change the country of an existing subscription. We won’t get into the mockups for that test here, but it turns out that the bug is reproduced in this case too (it was in the story).

So the bug happens when we change the country and open the dates screen.

But are those two steps really necessary to reproduce the bug?

To check, we’re going to do each of them separately and see if we reproduce the bug in each case. Let’s start by changing the country without opening the dates.

To do this, we pick up the subscription from the test case:

We change its country:

And we save it. Note that we didn’t open the dates screen.

Now let’s reopen the subscription and click to open the dates screen:

The dates are there, the bug is not reproduced, so it was necessary to open the dates screen right after changing the country. Opening the dates screen then flushes the dates.

But then, do we really need to change the country? Yes, because when we open a subscription and directly open the dates, we see that the dates are here, so the bug is not reproduced then. We saw that in the initial presentation of the feature.

We can deduce that opening the dates screen flushes the dates, but only if we’ve changed the country beforehand.

Now the question is: why? What’s going on when we perform those two actions in a row? It’s time to 3) Formulate hypotheses and check them in the code.

Step #3: Formulate hypotheses and check them in the code

Let’s think: what is the link between a country and some dates? The first answer that comes to mind is public holidays. Indeed, each country has its public holidays.

To validate this hypothesis, we won’t even have to look in the code. Looking in the code is typically slower than looking in the application, so let’s save it for when there is nothing else we can do.

Different countries have different public holidays, but different cities in the same country have the same public holidays. Let’s try to change the city without changing the country and see if we reproduce the issue.

We start again with the subscription of the test case:

Note that we use the minimal test case that we obtained with differential testing. In particular, no need to go through duplication. So we select another city in Germany:

And open the dates screen:

The dates are still there! The bug is not reproduced when we change city, only when we change country. This raises the probability that the bug is somehow related to public holidays.

The other feature that is related to public holidays is the automatic generation of dates. Let’s see if we reproduce the issue with the generation parameters filled out.

So we start again from the lesson subscription of the test case:

But this time we fill the generation parameters:

Now let’s go back and change the country:

And reopen the dates screen:

The dates are there, but not exactly the same. Contrary to Germany, Poland doesn’t have the 7th of April as a public holiday in 2034.

We can deduce that opening the dates screen is working out the dates, based on the country and on the generation parameters.

We can now formulate a hypothesis about the source of the bug: when we open the dates screen, the system tries to work out the generated dates if the country has changed. And something is going wrong when there is no generation parameters.

Now we can check this hypothesis in the code, and there is just a couple of lines that can confirm of infirm the hypothesis. We go check that targeted portion of code, and it takes only a few minutes to realize that the system is trying to generate with an empty generator, which gives an empty set of dates, and it uses this empty set regardless.

The source of the bug has been identified.

Now we should think of a fix, but that’s another story, that uses another method.

The more time you spend in the application, the less time you spend in total

Even if I’ve never worked for a school of harmonica, the bug I had seen in real life looked essentially like this one, and all the above reasoning is very close to how the analysis went down. With this method, we could diagnose the bug in a matter of minutes.

When you do maintenance, don’t start by looking at the code. Rather, play around with the application and reason about what test can help you narrow down the source of the issue. You’ll save a lot of time and frustration in your life as a software developer.

You may also like

Software maintenance can be fun – The quickest way to find the source of a bug

The post A Case Study for the Quickest Way to Find the Source of a Bug appeared first on Fluent C++.

All in all, maintenance gets the reputation of being an unrewarding activity, with low intellectual stimulation and not as worthy of a developer’s time as building a new feature, for example.

I love doing maintenance. Not because I like feeling lost in code that I don’t know. And neither because I like spending hours running in circles. And even less because I like the feeling of the touch of the F10 key.

I love doing maintenance because, if you have the right technique, maintenance can be fun.

In this article I try to explain that technique, with the goal that you come to like fixing bugs in the application you’re working on too (if you do, please leave a comment!). It’s not rocket science, and a part of it is in Code Complete. But it has enormous value because it can save you a large amount of time and frustration when working on that unjustly ill-famed activity.

Now if you’re wondering why we talk about that on Fluent C++, which is normally concerned with expressive code, the link is that this technique will save you from looking at a lot of code. So even if that code is not expressive and has poor design, it won’t be in your way to slow you down.

The slowest way to find the source of a bug

Before getting to the best way to identify the source of a bug, let’s see the natural way. The natural way goes like this: you get a bug report related feature X, you look around the code of feature X, potentially step through the codeline with the debugger, looking for the cause of the problem.

This is about the least efficient approach to finding the cause of a bug. But this is what we do naturally, and like pretty much everyone that’s what I was doing as a young sprout.

Why is this approach doomed to failure (or to a very long and painful road to eventual success)? It’s because if you start by looking at the code, you don’t know what you’re looking for. You hope to stumble upon the source of the problem by chance. It’s like looking for a specific street in a city, just by methodically walking around town until you run into that street.

And if you’re in a large codebase, it’s like walking in a big city. You may find it, but chances you’ll be dehydrated before then.

So the first piece of advice is don’t start by looking at the code. In fact, you want to spend as much time of your analysis as possible in the application.

But what to look for in the application then?

The quickest way to find the source of a bug

Step #1: Reproduce the issue

The first thing you want to look at in the application is checking that the bug is there. It sounds stupid, but it happens that the development environment is not quite in the same configuration as the one where the bug appears, and any further analysis would be a waste of time.

Step #2: Do differential testing

Ok now let’s assume that you do reproduce the bug. The next step is then to reduce the test case. This consists in trying slight variations of the original test case in order to refine the scope of the bug.

Step #2a: Start with a tiny difference

It’s going to be a little abstract here, but we’ll get to a concrete example later on. Say that the bug is appearing in feature X when it is in config A1. Other possible configs of the feature X are A2, which is very close to A1, and B which is fairly different from A1. And A2 is simpler than A1.

Since A1 and A2 are so close, the bug will likely be reproduced with A2 too. But let’s test A2 anyway.

If the bug is NOT reproduced in A2 then great, it means that the bug is specific to A1, and lies in the difference between A1 and A2. If you can refine the test by checking another config A11 versus A12, then by all means do. But say that you can’t go further that A1 versus A2. Go to Step #3.

But if the bug is also reproduced in A2, you know that the bug is not specific to A1 nor lies in the difference between A1 and A2. But you don’t know where the source of the bug is yet.

Step #2b: Continue with larger differences

So you test less close configs, and simpler ones if possible. B, for example. Since B is not close to A1, it’s likely that you don’t reproduce the bug in B.

But if you DO reproduce the bug in B, it means that you’ve been lied to: the bug has nothing to do with A1. But it’s ok, business people didn’t do it on purpose.

This discovery brings you two things:

• it simplifies the test case, if you did find a simpler config B where you reproduce the issue,
• it tells you that the bug is probably not related to feature X after all. So you need to do differential testing between feature X and another, close feature X2. And then a remote feature Y. And so on.

Step #3: Formulate and check a hypothesis

You now have a pretty accurate location for the bug. This is now the time to formulate a hypothesis about what is causing the incorrect behaviour. What could go wrong in this confined space of the application? If you see several things that go wrong, what’s your gut feeling for which one is the most likely?

Then, and only then, you can look at the code. The point of looking at the code is to confirm (or infirm) your hypothesis. So you go directly to the portion of code that your differential testing pinpointed. It should be fairly small. Fire up the debugger (or run the code mentally if you can), check if your hypothesis is confirmed.

If it is, congratulations, you identified the source of the bug. If it’s not, do Step #3 again until a hypothesis is confirmed.

A binary search for the root cause of a bug

If you don’t practice this technique or something resembling it yet, it probably sounds somewhat complicated. In that case, a nice analogy is to compare this with linear search versus binary search.

Starting by looking at the code and searching for what’s wrong in it is like linear search: you walk your way through the code, function by function or line by line, until you encounter the source of the issue.

However, with the method we described, that is operating with differential testing and hypotheses is like binary search: it consists in making checks at some targeted locations, and decide each time for a new direction to look into. And the same way binary search eliminates huge chunks of the collection from the analysis, differential testing and hypotheses discard huge portions of the codebase that you won’t have to look into.

Sure enough, binary search takes more mental effort to implement than linear search. But the method has two advantages: A) it’s way faster and B) it requires you to think.

This latest advantage is what makes maintenance fun. Every bug becomes a challenge for your mind, a sort of puzzle. But one for which you have a method, and of which the resolution is only a matter of time.

Next up, we will go through a concrete example of bug-finding to get some practice at applying that method.

The post 3 Steps to Find the Source of a Bug Quickly appeared first on Fluent C++.

If you answered Yes to any of those questions, be aware that you’re not alone. Quite the opposite, in fact. You only need to talk to people for more than a minute at meetups or conferences to realize that a significant amount of developers suffer from legacy code.

It makes me sad when I see competent and motivated developers losing faith and ending up suffering from the questionable quality of the code they’re working on. Some resign themselves to it and even spend years suffering from legacy code on a daily basis!

It doesn’t have to be that way. One of the ways to get out of that spiral is not to let yourself be bullied by bad code.

Instead, show bad code who the boss is.

Legacy code is a bully

As a young developer, starting to work in a codebase that has been there for a while can be a challenge. Even more so when you just graduated from CS school where you’ve mostly worked on libraries or ad-hoc projects. Being thrown all of a sudden into a big codebase that has evolved over years can be disorienting, to say the least.

It’s like you’re the new kid at school, and the big bullies don’t plan on making your life easier.

Big functions, big objects, mysterious names, inconsistent and duplicate components, all those bullies firmly oppose themselves to your understanding of the code. They’ll do all that is in their power to slow you down in your analyses, and even when you make a fix and think you’re done, they will throw an unexpected regression into your face.

But kids get bigger, bullies end up going out from school, and some kids even grow into the new bullies that will take care of the new generation.

This is where the metaphor breaks down. Even if you can grow as a developer, time doesn’t make legacy code go anywhere. It’s waiting for you, day in and day out, trying to get in your way. Some people spend years suffering from it!

If you’re in that case, I want you to take action by fixing the code. But not any action. I want you to come up with a targeted strategy, that aims at making your legacy code less powerful in its ability to make your life miserable.

Hit it where it hurts

There are so many things you could fix in a legacy codebase, so many places that would deserve a little makeover, or even a total refurbishing.

But you have to face the hard truth: you won’t fix be able to fix it all.

Codebases that took years of active work that involved several to many people are vast. Fixing every last issue would take months or years, and you have client requests to satisfy at the same time. Going off to a crusade trying to fix everything that’s wrong in the codebase is an utopia. Similarly, throwing it all to the bin and rewriting it from scratch is often a terrible idea.

However much time your company policy allows for refactoring, you have limited resources. So you need to pick your battles very carefully.

How to evaluate which refactoring is worth your team’s time? It’s comes down to a basic economic decision: you want to maximize the value and minimize the costs. But what are the value and costs of such refactorings?

The costs of a refactoring

The costs of a refactoring include the time to actually change the code, but not only.

Changing obscure code requires you to understand it first. So if you’re not clear about it already, you need to factor that analysis time in. Also, such changes could cause regressions, so you need to factor in the time you think it will take to stabilize your refactoring.

A refactoring that introduces boundaries and interfaces may give you an opportunity to write some unit tests around it, which may take some time too.

Also, it you’re tackling a buggy part of the code, chances are that somebody else in the team is currently trying to fix a bug in that same code, and integrating both your fixes will need to solve a merge conflict.

The value of a refactoring

Here we’re talking about diminishing the capacity of the codebase to get in your way. So it has to be code that you read – or debug – frequently. There is little point in refactoring code that you don’t interact with often. Even if you see how to make it better, and even if you feel it wouldn’t be too hard.

This brings up a very important point: why do we strive for good code? For art, because it’s beautiful? For morality, because it’s wrong to write bad code?

No. We write good code because it helps the business. Good code leads to less bugs, faster integration of new features, less turnover in the company. All those are business reasons. Refactoring a piece of code that doesn’t pose a problem to the business is tantamount to refactoring the codebase of another company while we’re at it.

Well, in fact there is another reason to improve code quality: it makes our lives easier, as developers. Sure, this in the interest of business too, but we can see it a goal in itself too. Anyway, refactoring a piece of code that doesn’t hinder us too much is wasted effort in that respect too.

In particular, and I know it may sound surprising at first, don’t do a refactoring just because it’s cheap. If it doesn’t bring enough value, you will have wasted time. You’ll be more grateful to have spent an afternoon making one big hit to a targeted part of the code, rather than 100 little flicks all over the place.

The most efficient approach in my opinion is to be value-driven: pick the 2 or 3 things in your code that slow you down the most or are the most buggy, and that have a reasonable cost of fixing. Conversely, don’t be cost-driven: don’t pick the cheapest fixes you could do and see which one is the most helpful.

Let’s now see what sort of hits could have a reasonable value/cost ratio.

Where does it hurt?

Before giving some suggestions, remember that you’re the one in the best position to figure out your most valuable refactorings. What annoys you the most in your codebase in a daily basis?

Also, you can survey your team to ask their opinion on that question, and decide together on what to take action on.

Here are some suggestions, and you’re welcome to suggest other ideas based on your experience:

Slice up a big function

This is a classic one. Big functions drown readers of the code into low-level details and prevent them to have a big picture of what the function is doing.

Identifying the responsibilities of that function allows to split it in several sub-functions and put explicit names on them, or outsource part of its work to another function or another object.

If you come across that function often, this refactoring can bring a lot of value.

Slice up a big object

Some objects get extra responsibilities tacked on one by one over time, and evolve into massive behemoths that sit in the middle of the codebase.

Splitting their members allows to manipulate lighter structures that take up less mental space in the mind of a reader.

Sometimes, slicing up a big function leads to slicing up a big object, if the various sub-functions operate on various, but distinct, parts of the object.

Expose side effects

Big functions making side effects on big objects are notoriously hard to follow. Making it clear what effects a function has on objects helps following along and being less surprised when debugging code.

One way to do this is to make more objects and methods const, and separate the data that is modified from the data that is const in an interface.

Having no side effects is even better but, as a first step on a large function, this is not always realistic to aim for.

Use names that makes sense

Bad names can send you on a wrong track, and make you waste a lot of time.

The value of changing some names can be high, and its cost varies from low for a local name to higher if the codebase uses the name broadly and you don’t have appropriate tooling.

What else would you include as refactorings with high value and reasonable cost?

In any case, don’t let yourself be bullied by legacy or otherwise bad code. Talk with your team, identify the painful points and how to fix them at a reasonable cost. Start small, with a couple of bad functions or objects.

And when you’ve identified you targets, hit them, and hit them hard.

Related articles:

• Using Bad Code to Learn How to Write Good Code
• The Right Attitude to Deal with Legacy Code

The post Don’t Let Legacy Code Make You Suffer. Make <em>It</em> Suffer appeared first on Fluent C++.

Have you ever struggled to understand a codebase that was bigger than you?

Most of us go through this experience more or less often in our career, and this is not a simple thing to do. Chances are you’re in this situation right now.

During one occurence of the Software Craftsmanship meetup somebody was asking for advice because he had been thrown into a gigantic legacy codebase with no documentation, no architecture and discouraged developers. The total opposite of an expressive codeline.

Well, even when the code isn’t expressive, there are ways to understand its meaning.

Lots of developers face this sort of situation, with varying degrees of intensity (his case was pretty bad). Even though the codebase I’m working on is in better shape than what he was describing, I too have had to figure out the code of a large codebase, with some parts being legacy code. And today I’m even training younger developers at getting better at this.

Now that you’ve adopted the right mindset towards legacy code, let me share with you the most efficient ways I have found to get up to speed with a large codebase, even if its code isn’t always expressive.

Those tips will help you be more efficient and, I hope, boost your motivation as a software developer.

1) Choose a stronghold and conquer an empire

Do you remember those strategy games where you start with a little base and then you have to develop and explore the surroundings, which are blacked out when you start the game?

I find that these games are an excellent comparison for a codebase.

One efficient way to start the exploration of a legacy codebase is to find a place you understand very well. This will be your stronghold to start the game with. And it doesn’t have to be big! It can even be one line of code.

Let’s take an example. The software I deal with does various sorts of computation, but there is one very simple one: a linear interpolation. It consists of estimating a value between two values that are already known.

And we know its formula perfectly well: y = y0 + (x – x0) * (y1 – y0) / (x1 – x0), independantly of any software representation. I’ll choose this as a stronghold. Therefore I’ll focus on locating it in the codeline.

A good stronghold needs to be a bit specific. For instance, a function that puts a string in upper case in not in itself a good stronghold, because it is typically used in several unrelated places across the codebase. Rather, some business code that calls this function in a context that you know in the application is a better stronghold.

Once you find your stronghold, clutch to it. It constitutes a starting point from which to begin your exploration of the codeline.

Indeed, there is a high chance that you can figure out the immediate surroundings of that one line of code. And little by little things start to make sense. Little by little you’ll be expanding the area you’re comfortable with, and the dark area on the map will be shrinking.

I found this technique really helpful for starting out. However it takes time, and it won’t let you get to the ends of the world very shortly, particularly if your codebase has hundreds of thousands or millions of lines of code. This is why you need more.

2) Work your way up and down a stack

For this one you’re going to need your manager (or someone who’s familiar with the architecture of the application) to sit down next to you. Or if you’re the one who knows, sit with your padawans for this one.

The idea here is to fire up the debugger, find a judicious place in the code to put a breakpoint, and launch a use case in the application. The experienced person is here to choose the ‘judicious’ breakpoint, that is one in a deep stack of a typical use case of the application.

Then look at the call stack. It displays in one shot all the layers of the application involved in this use case.

This way you can learn a lot about the architecture of your software: what the main modules and the main frameworks are and how they relate together. A call stack tells a long story. Plus, some debuggers display the module name for each function in the call stack. Visual Studio does it if you do Right click > “Show module name” on the call stack.

You can repeat this experiment for several call stacks in the same use case, in order to get a grasp of the sequencing of the calls.

3) Start from the inputs and outputs of the application

If you don’t understand the code and no one is there to explain it to you, there is still hope. You can at least find someone who understands the application from a user point of view, or at least partly.

Then focus on something you understand in the application and that you can visualize, in the Graphical User Interface, or in any other form of input and output. Then find where this input comes into the code.

Once you’ve found it, seize it like a thread and follow it, until you reach the code of one functionality that you recognize, even if this functionality boils down to just one line of code. This will be your stronghold, and then you can apply advice #1 above.

4) Make a refactoring to decouple the code

Refactoring a piece code is a great way to get familiar with it. But not all refactoring will give you the same amount of knowledge for the same time invested in them.

Indeed, even though the refactorings that clean up the code have value, here I’m talking about refactorings that change the structure of the code. Or sometimes it rather looks like putting a structure into place. And you can achieve that by decoupling components.

But don’t worry, you don’t have to revise the architecture of the whole application to do this! You can just tackle a function and split it into sub-functions. This will give you a better overview of the sequencing of actions in this function, as well as a detailed view of the data that comes into play in it.

You can also decouple data processing from objects. This one doesn’t apply in all cases but when it does, you hit it big.

For example, imagine a class that contains data members and methods that operate on them. If this data processing is also used by another class, then the two classes are coupled and the code is weird. In this case you can take the behaviour out of the first class, so that both classes uses this extracted behaviour, and not each other.

The code becomes simpler and more extensible afterwards. But in the process, you’ve seen all the details of the processing of this particular data. It makes you learn a lot about this part of the program, both in terms of code and in terms of funtionality. This was the first refactoring I made on the codebase I’m working on today, and it made me an expert on this part of the application. Special thanks to my fantastic manager Patrice for teaching me this.

If you want to dig more into refactoring, Refactoring by Martin Fowler is a classical book on the subject. And refactoring legacy code goes hand in hand with the topic of tests, all of which you can read about Working effectively with legacy code by Michael Feathers.

5) Find a “padded room” function

This is a technique that I often use with the younger developers that I manage. I pick a big function in the area they’re going to work on, that has a complicated implementation, but that has little to no dependency on anything else. You have some of those functions in your codebase, don’t you?

I find they are a great place to sharpen your code reading skills. It takes a little bit of time but you end up understanding and then mastering a least some parts of it. And like in a padded room you can’t hurt yourself, because the function only goes so far and you don’t have to get lost into another complex function and another, etc. It is self-contained.

This exercise in the padding room function makes you more familiar with the coding style of the codeline. I’m not saying that it is always a model for writing your own code, because some legacy codebases don’t exactly have the best style. Rather, it will make your eyes used to the patterns of the codebase, and you can apply this skill pretty much everywhere else inside it to understand code more quickly.

It will come with time anyway

Even if tackling a large codebase that you haven’t written yourself seems like a dauting task at first, it gets easier with time. The bigger the area of code your master and the more you understand what your application is supposed to do, the more quickly you’ll understand a new part of it.

But this comes with time, and a steady amount of effort. Find your stronghold, analyse your stacks, decouple the code and hone your skills in safe padded room functions. Then conquer the world of your software.

Related articles:

• The Right Attitude to Deal with Legacy Code

The post 5 Tips to Find Your Way Around A Legacy Codebase appeared first on Fluent C++.

But if you’ve been working with it for a while, you may be able to navigate this code with ease, and maybe you don’t even see its little weirdnesses any more.

This is a dangerous situation. It makes it easy to overlook some design issues and to fail to recognise that it is difficult to integrate new developers into this code.

There is one thing we can start with: transfer our knowledge into naming.

Making an impact with your knowledge

Consider the following big class:

class rvDTP_CLASS
{
public:
    void soGR(int get);
    virtual int getObjectID();
    void evaluate(EvaluationParameters& parameters);
    // ...
    // lots of other member functions...
    // ...
};

This is inspired from a true story (although the code has been anonymized).

Imagine you’re inheriting that code. At the beginning, all this means nothing to you. When you join the project you wonder, puzzled, what does soGR means?

After making a few features and fixes in the surrounding code, you come to realise that soGR is the function that interacts with the database. It allows to save or load the contents of the object, and the int it takes indicate whether it should save or load. A bit of the class starts making sense!

And then you live on your life, exploring and working on other unrelated parts of the code.

Later on, you come back to the rvDTP_CLASS, from a code handling UI. This code is asking the class the result of getObjectID(). A bit of code exploration makes you understand that the various derived class from rvDTP_CLASS return their own ID, and this ID correspond to a type of display screen.

getObjectID lets the UI layer know which screen to load in order to display the object corresponding to a derived class.

You can now map every class to something in the UI. Great, that gives you a concrete image of what rvDTP_CLASS and its derived classes represents. In fact they represent the product (let’s assume that “product” means something in the domain of this application).

Months pass, and little by little you get a finer and finer understanding of the class, its responsibilities and each of its member functions. You possess knowledge.

New people join the team, and they’re completely bamboozled when they see the rvDTP_CLASS and its member functions for the first time. To help them make the fix they need, you tell them what you learned back then: soGR interacts with the database!

But this is not a good way to pass knowledge, as I’ve come to realise, and I’ve certainly been guilty of giving this “help” to more junior developers.

Passing on the knowledge is good. But passing on to the next person is suboptimal. What you want is passing it on to the code.

Naming things for what they are

If you’ve been working with a given area of code for a long time, you may no longer realise what it looks like to someone seeing it for the first time. But their point of view is crucial to assess how expressive the code is.

So when someones asks: “what is soGR“, the best way isn’t to answer that it handles the interaction with the database to save and load the object. A better way is to bake this in the code:

class rvDTP_CLASS
{
public:
    void loadOrSave(int load);
    virtual int getObjectID();
    void evaluate(EvaluationParameters& parameters);
    // ...
    // lots of other member functions...
    // ...
};

But this new name can make you cringe. A function called loadOrSave? This looks like a terrible name. It’s screams that it’s in charge of two responsibilities!

While you’re at it, rename everything:

class Product
{
public:
    void loadOrSave(int load);
    virtual int getScreenID();
    void evaluate(EvaluationParameters& parameters);
    // ...
    // lots of other member functions...
    // ...
};

And this makes you cringe even more. A class that mixes DB, UI and business logic? This is the kind of counter-example we see in design books!

The thing is that it’s been there all along, but it was disguised behind mysterious acronyms.

Now you no longer have to explain what rvDTP_CLASS, soGR or ObjectID means. But you have a new type of problem.

You unearthed skeletons

Until now, the code looked mysterious. But making the renaming fix made it visible that the code has a poor design. If you’re in charge of this code (and you should consider yourself in charge of any code you work with), it can make you cringe even more.

But it is important to keep in mind that unveiling problems is a step towards fixing them.

Indeed, now you can better see the big picture of the class. Until now, your knowledge may have been composed of bits and pieces gleaned from individual explorations of the code, but after renaming its members, you see the class for what it is, as a whole.

This is the right time for deciding what to fix and when to fix it. For example in this class we’ve seen two possible improvements:

• separate the load from the save function
• separate the UI, DB and business logic of the class

When you do that, everything should become easier: the code will become easier to understand, explain, and unit test.

But instead of jumping into refactoring, make sure you’ve renamed as many things as you can in the class. Once you understand the code, renaming is fast. The more you can rename, the more quickly you can get an overview of design issues of the code.

Once you have a list of improvements to make, this constitutes a technical roadmap for this class.

Then comes the step of prioritisation: is this class the most important in your code? Are there other classes for which you should also create a roadmap?

If you’re working with legacy code, there may be more skeletons than you have the resources to deal with, so you need to choose which ones will bring the most value. To evaluate the value of refactoring projects and choose the best ones, refer to chapter 12 of the Legacy Code Programmer’s Toolbox.

The power of naming

Once you have acquired knowledge, transfer it into correct names in your code. The operation of renaming is typically fast and with very little risk.

Even if naming doesn’t improve the behaviour of the code per se, it is the first step towards understanding, integrating new joiners, decoupling, modularisation, unit testing, and ultimately an application that evolves faster and has less bugs.

You will also like

• A Concrete Example of Naming Consistency
• How to choose good names in your code
• The Legacy Code Programmer’s Toolbox
• Making Wrong Code Look Wrong (Joel on Software)

The post Make Bad Code Look Bad appeared first on Fluent C++.

Those non-technical things aren’t taught at school or in C++ books. Nevertheless, I consider them just as important to produce good code. They’re especially valuable since it took a while of professional experience (at least for me) to figure out.

This is one of those few posts of Fluent C++ that doesn’t show any code snippet, but shows you something necessary be a good software developer, in my opinion.

It’s about the word “can’t”.

The C-word

I realised the importance, frequency of usage and impact of the word “can’t” by reading Game Changers. It’s a book which is not about software, but about improving various aspects of one’s life. It’s written by Dave Asprey. In this book, Dave synthesised his takeaways from podcast interviews with hundreds of individuals that changed the game in their respective fields.

In one of the first chapters, Dave recommends to ban, partially or completely, some words from our vocabulary. The first one is the word “can’t”, and it’s to ban completely.

When you say “can’t” you’re creating a limit, even if an unconscious one. You’re blocking yourself and others from achieving great things.

There is virtually nothing that we “can’t” achieve. Some things we haven’t figured out yet. But with thinking, time or energy, a lot of things we deem unreachable are in fact within our reach.

To prove his point, Dave encourages us to watch around us how often we or the people we interact with write or say “can’t”. I’ve tried, and we do say it a lot. I said it a lot.

“We can’t do that”

As a team lead one of my roles is to assess the feasibility of developments, break them down into smaller bits and find a path of execution.

I used to say expressions such as “this we can do” or “this we can’t do”. But this is a terrible way to express oneself.

If you think you also say “can’t” sometimes, let’s see how we can do better. Let’s consider the various situations where a developer says: “I can’t do that” and try to see what we really mean, and how to go beyond the arbitrary limits we fix for ourselves.

We won’t have the time to do that

If you think that there is too much to achieve given the constraints you’re given (time, budget, etc.), say so explicitly but without the word “can’t”.

“Can’t” creates an unnecessary limit. If you think the project you’re working on won’t give the desired results, it’s a time to negotiate with the business people (PO, PM, insert your favourite acronym here) of the company. One way is to identify the features that matter the most and deliver them first. Or check if some features are quick to implement to get their desired outcome.

But in any case, leave the possibilities open.

We don’t know how to do that

When you’re asked to implement a feature or fix a bug, if you tell that you don’t know how to do it, you convey a completely different message than if you tell that you can’t.

If you don’t know how to do something, there are ways to move forward to help you acquire that knowledge. For example you can agree to allocate a time to figure out a way, for example by:

• analysis the existing code,
• brainstorming between developers,
• discussing with architects,
• finding a similar feature and analysing it,
• asking more experienced developers,
• etc.

But if you say that you “can’t”, you’re closing the door to any step to move forward and eventually succeed in implementing the desired feature.

We’re downright sure that this is impossible

I once had (in essence) the following conversation with an architect called Damien:

– Jonathan: “I need to implement feature X, but with the framework Y that this code uses, it’s impossible.”

– Damien: “Is it?”

– Jonathan, thinking that “impossible” is in fact not far from “can’t”: “You know what, let me double check and get back to you.”

I was convinced that framework Y wouldn’t support feature X but, for all the above reasons I was also convinced that nothing is impossible for a software developer.

So I dug into framework Y, read more documentation, stepped through the code, thought, stepped through again, read again, thought again, tried, failed, thought again, asked around, tried again, and finally… succeeded.

I had found a way to implement feature X with framework Y.

This was a delightful experience for me who went beyond what I thought possible, for my PO who got what he was hoping for, and I think that Damien was happy too.

There is nothing specific to me, Damien, framework Y, feature X or my PO. This story can happen to any software developer. Our main tool is our thinking, and it can achieve more that we think (I realise now there is a recursion in this sentence, right?).

If you think something is impossible to achieve, think more and try again. There is a good chance it’s within your reach.

“This can’t be”

Another situation where we could be tempted to use the word “can’t” is when looking for the cause of a bug.

Some of the longest bugs to analyse are those where the root cause lies where we don’t think to look. In those cases, we’re so convinced of our assumptions that we think, or sometimes say aloud, that some things “can’t be”.

If the problem is that something we thought couldn’t be actually happened, the longer we stay convinced, the longer the debugging session.

When debugging, it is important to realise that the execution of code is too complex to fit in our brains, that’s why we have computers in the first place, and everything we think about how the code behave is assumptions.

We need those assumptions, otherwise we’d spend an infinite amount of time examining each detail. But an efficient mindset for debugging is to assume that everything is possible, and to assess the likelihood of each assumption.

Once again, the word “can’t” doesn’t help. In debugging, “can’t” can only lead to a waste of time and energy.

“Can” will make you friends

Beyond its dramatic effects on your achievements, the usage of “can’t” can have an impacts on your relationships with other people of the company.

As John Sonmez explains it in his excellent Soft Skills, the job of software developer is a social one. We spend a sizeable part of our day interacting with other people: other developers, QAs, business people, etc.

Greeting the request of somebody with a “I can’t do that” isn’t the best way to foster relationships. Compare it with “I’d like to help you, but I’m currently missing X, Y and Z to achieve what you’re asking, how could we get those?”. Doesn’t that sound better?

In conclusion, ban “can’t” from your vocabulary altogether. Pay attention to when you’re about to say it, or when you write it in an email. If you currently use this word, this change will make you see another aspect of software development.

You will also like

• You Should Refuse to Develop What You Don’t Understand
• The Legacy Code Programmer’s Toolbox
• Copy-paste developments
• Technical Debt Is like a Tetris Game

The post “Can’t” Is No Word for Software Developers appeared first on Fluent C++.

This was the largest project I’ve ever worked on. We were the four of us and it took us several weeks to root out all the usages of this old technology. In the end, we managed to decommission it in the estimated time, and our code is now much more expressive.

Although the project was a resounding success, several things could have made it fail.

After the completion of the project we made a retrospective session, where we reflected on what we did that helped us achieve this challenging project, but also on what had set us back and could have made the project a failure.

You’ll find those reflections synthesised into the following 6 takeaways. They’re not specific to this project and I think they’re good practices for any development project to follow.

1. Don’t let the same error happen twice

Since our code changes spanned widely across our codebase, many tests came out red. Making a test red is not a problem in itself. After all, if we weren’t able to break them, tests would be useless.

What matters more is how quickly we can analyse red tests and fix them. When several hundreds of tests are red, you want to spend as much time as possible to analyse and fix each of them.

One way to do that is to make sure not to analyse the same type of root cause twice. Indeed, one given root cause could be repeated in the code, and be responsible for several tests being red. Saving the repeated analysis then saves some precious time.

Whenever you fix a bug, try and think how to make sure the same problem hasn’t happened somewhere else. And if possible, detected this automatically.

Compile time detection

The most efficient automatic detection is at compile time.

For example, at one intermediary step of the development, we had some void* pointers coming from the old technology that we had to pass to a function:

void functionExpectingVoidStar(void* pointer)
{
    // ...
}

We discovered once by analysing a broken test that a call site passed by mistake a wrong pointer, that happened to be typed. And since in C++ all pointers convert implicitly to a void*, the function accepted it the typed pointer we shouldn’t have passed it.

After fixing the bug by passing the void* in this context, we changed to interface to this:

template<typename T>
void functionExpectingVoidStar(T* pointer) = delete;

void functionExpectingVoidStar(void* pointer)
{
    // ...
}

This way, the interface no longer accepts typed pointers (in general you want to use typed pointers rather than void*, but in this case we had void* objects to work with in the first place).

When rebuilding the code, all the other call sites that passed wrong pointers bubbled up in compilation errors. Fixing them at this point fixed the corresponding broken tests with no extra analysis time required.

Runtime detection

One great way to detect errors at runtime is to use asserts. A broken assert is a blessing: it gives you the stack where the problem is happening on a silver plate.

If you can’t detect a bug at compile time, use an assert to detect it as early as possible as runtime.

2. Don’t expect too much of your dev plan

Large projects require preparation. In this particular project we had spent hours brainstorming about the best way to tackle it, how to break it down into small deliverables, and we had tried to anticipate issue and to anticipate how to solve those issues.

This analysis helped us craft our dev plan: the successive steps that were to lead the code from where it was to where we wanted it to be.

And then we started the project.

During the first steps, the dev plan guided us fairly well. But at some point, the reality of the code didn’t match what we had planned.

In this case, the thing to do immediately (I wish I did it more quickly) is to consider changing the dev plan. Or throw it away altogether if the reality is too far away from it.

As Sir Arthur Conan Doyle makes it say to Sherlock Holmes: “It is a capital mistake to theorize before one has data. Insensibly one begins to twist facts to suit theories, instead of theories to suit facts.”

There is psychological resistance against abandoning a dev plan we spent so much time crafting, and that we based on to provide estimates to the management. But if the dev plan was based on our vision of the code at the time, and that the code is in fact more complex, then the best course of action is to change the plan.

And with legacy code, the code is always more complex that you think it is. So don’t expect your dev plan to be a guide taking you by the hand to a destination. See it more like a general direction into unmapped territory.

3. Verify your hypotheses

Like we just saw, we shouldn’t expect the dev plan to guide us smoothly to the end of the project. But some things can increase the life expectancy of a dev plan. One of them is to check hypotheses.

A dev plan is a thought experiment: you plan the changes in code you will execute to reach an objective. To do this you make hypotheses.

There are at least two types of hypotheses: how the code is now, and how changes will affect it.

If you’re familiar with the codebase, you may be tempted to consider those hypotheses as facts. The dev plan builds on those hypotheses and if they turn out to be wrong, the dev plan crumbles.

So to give the best shot to your dev plan and to your project, check your hypotheses as much as possible.

To a large extent, you can check how the code is now. However, checking how changes will affect it is more challenging: if you start changing the code to check, then you’re starting the project itself.

One compromise is to make some targeted changes in a branch that you’ll throw away. This way you can poke at the code and see how it reacts, as well as the effect of your experiments on the tests.

Two of my structuring hypotheses turned out to be wrong in our development. I’m lucky we adapted quickly when we realised that. Since then, I’m much more careful to check my hypotheses when planning.

4. Don’t let stuff build up

We programmers love to code. And it’s easy to get carried away into coding, and focus on improving the code for days in a row.

But there are other things than code to monitor. For example:

• code reviews of the changes made by other developers on the project,
• tests,
• CI errors,
• …

Be sure to treat those at least on a daily basis. Letting code reviews accumulate leads to frustration for everyone: the authors are waiting for feedback on their changes, and the reviewers end up facing a mountain of code to review.

For other reasons, letting code accumulate without making sure the tests are green makes everything more complicated. Changes checked in recently over code that had failing tests are blocked because of those tests. And the wider the span of commits with red tests, the harder it is to pinpoint the root causes of the regressions.

Have a good hygiene for tests, code reviews, CI errors, and the like. Treat them on a regular basis, and don’t let them build up.

5. Communicate intensely and asynchronously

One of the things that made our project move forward quickly is the intense communication between the members of our team.

An interesting note is that we never saw each other during the project: it started after the coronavirus outbreak and we were working from home.

We’re using Microsoft Teams, and we created a channel dedicated to the project. You can do the same type of channel with Slack too.

The advantage a channel over email is to have all the information located at the same place. Microsoft Teams also allows to have one or more spreadsheets in a Microsoft Excel embedded in the channel itself, in the form of a tab, which is quite convenient.

And the advantage of a channel over sitting next to each other and talking is that we interrupt each other less: you can always finish what you’re doing before checking the notifications of the channel.

6. Check in and rebase often

Having several developers working on the same codebase is challenging. Indeed, if two people modify the same line of code, there is a merge conflict. And if one changes the code that the other calls, then there could be passing tests locally for every one, and overall a break in the tests.

There is no magic to solve those problems, but one way to mitigate them is to avoid as much as possible to work on stale versions of the code.

Check in your code often, so that others can work on top of your modifications, and not concurrently. And rebase your code often, so that you have in local the latest changes of your fellow developers.

Share your tips now

Those are the 6 tips that made the most difference for my team, on this project. I hope they’ll be useful to you too.

Could you share the tips that made a difference for your team, on a recent project? Leave them a comment below.

You will also like

• You Should Refuse to Develop What You Don’t Understand
• 3 Types of Toxic Software Projects
• Better Macros, Better Flags
• Which One Is Better: Map of Vectors, or Multimap?

The post 6 Tips to Make Your Development Project More Likely to Succeed appeared first on Fluent C++.

But what is a good developer, to begin with?

Let’s reflect on what we need to do in our jobs as software developers to identify what is important–and therefore what we have to master in order to become “good developers”.

Good developers write good code

As software developers, our mission is to ship software that works. And what is software made of? Code, of course!

What comes out of this simple analysis is that if you want to be a good developer, you need to be able to write good code.

Fine. But now we’re left with a new question: what is “good code”?

To answer this question, let’s think about what code it useful for. Code is what makes software, and the mission of developers is to make software that works. So following this, good code is code that works.

Except that there is a hundred ways to write code to make a feature work. But all those ways are not as good as each other. Note that in code that “works”, I’m also including the fact that it runs fast enough, so I’m not talking about which code has the best algorithmic complexity.

The differences between the various pieces of code that all “work” is their design. So good code is code that has good design.

Bear with me, we’re getting there. We now need to define what “good design” is.

Once we’ve written a piece of code that works, why does its design matter in the first place? It matters if someone is going to come back to this code. Let’s call this someone Bill. Bill can be you or can be anyone else in the company. Bill can even be someone who is not here yet but will be recruited in the future.

So a good design is a design that will make Bill’s life easier. As a result, a good design needs to be understandable. If we unroll the logic we’ve just built, a good developer can produce code that is understandable.

But this is only a part of the picture. To be a good developer you also need to do an great job when you are Bill.

Good developers can work with any code

How much time do you spend writing code every day? Even if you work as a professional software developer, you probably don’t spend all day coding. You probably spend more time reading code than writing it.

Indeed, we read code all the time. We read code to analyse it and think about how to integrate new features. We read code when we debug maintenance issues. We read code during code reviews, when writing documentation, or simply when we help out another developer with his task.

As software developers, we read a lot of code. We spend much more time being Bill than writing code.

As a result, we need to embrace our Bill’s responsibilities. On top of writing expressive code to make Bill’s life easier, we need to figure out how to work with existing code. Because that is what we do the most in our daily work. We are Bill.

Understanding code

On top of giving instructions to the machine, the purpose of code is for a developer to communicate their intent to other developers. Like we said, we write code with good design for Bill to understand.

But there is code out there, that is not easy to understand. A good part of this code is what we collectively call “legacy code”. If you’re a software professional, you probably have to work with legacy code.

I’ve worked for over 7 years in our industry, I go to a lot of conferences and user groups, some of which I’m an organizer of, and I have a popular blog about writing expressive code. With all this I get to talk with a lot of developers, and I can tell you one thing: legacy code is everywhere.

Since a large part of your job is about reading code, and that you get to work on tough code, to be a good developer you need to be able to read code you don’t know and quickly make some sense out of it.

Fortunately, there are techniques to understand unfamiliar code. Here is a practical one: when you read a function or a method for the first time, start by looking at its end first.

Indeed, functions often have a progression with intermediate objects and actions, that leads to deliver a final result or effect that is located at its end. If you start by looking at that, you’ll get an idea of where the function or method is going, and it will make the reading of the rest that much easier. Sometimes, it will even save you from reading the rest at all, because you’ll have understood what the function is about.

Of course, to know what a function is about, its name and parameters should be enough. But there is code out there where functions don’t have a name as informative as they “should be”.

Peeking at the end of a function or method can save you a great deal of time. This is one of the 10 techniques to understand legacy code that are presented in The Legacy Code Programmer’s Toolbox.

Humility

When you’re Bill, it can be tempting to blame the person who wrote the code you’re trying to figure out. After all, their job was to write code with good design, and if you can’t make sense out of their writing, then they didn’t do such a good job.

You may be right or you may be wrong. Maybe it was a difficult piece of code to write, and that we wouldn’t have done a better job if we had had to write it ourselves. Maybe we’re lacking a piece of context. Or maybe the person who wrote it didn’t find the optimal solution indeed, but who always find the optimal solutions after all?

The thing is that it doesn’t matter. The code is here, and it’s what you have to work with. Don’t think about whether the author did a good job or a poor job designing the code, unless you’re doing this for the explicit purpose of improving the code or improving your skills.

Focus on what matters

What does matter in your ability to be efficient when working with existing code is what you know about it. In software engineering like in many places, knowledge is power.

There are plenty of ways to increase your knowledge about your codebase. One of them is to write a piece of documentation on a region of code you don’t know.

It can seem surprising at first: if you don’t know a piece of code, how can you write anything about it?

If you start documenting little by little what you discover in a region of code, this will direct your research. By explaining what you just start understanding, you’ll discover questions to be answered in order to complete your explanation. This is very valuable because it gives you specific things to look for in code.

Little by little, your exploration goes from a random one to a a directed one. Until you know your way around the region of code.

Note that there are plenty of other practical ways to increase your knowledge, and more generally to be more efficient when working with legacy code.

It’s still easier to work with good code

If we’re spending most of our time in the role of Bill, reading and working with existing code, does it matter much to be able to write good new code after all?

The answer is yes, because the code you produced will be used by Bill. And even if it is Bill’s responsibility to be able to work with any code, you want to make his work as easy as possible.

Writing code is about writing more than about code. You send a clear message, you reader open their eyes wide, and you hope that you guys will meet in the middle.

You will also like

• The Legacy Code Programmer’s Toolbox
• The Legacy Code Programmer’s Toolbox is out
• It all comes down to respecting levels of abstraction

The post Great Developers Don’t Just Write Great Code appeared first on Fluent C++.

On my end, I’m currently fighting the spread of the virus by:

• washing my hands often,
• working from home,
• limiting my interactions with other people.

But apart from that, I’m sitting on my (carefully washed) hands and doing nothing to help.

The French President told us that the lives of the elderly are threatened. This means that our families are in danger, and in the meantime I’m just using soap and staying away from people.

On the other hand, we developers have valuable skills:

• we can read code,
• we can write code,
• we’re used to learning stuff.

And with code, we can do anything.

For that reason, I am convinced that we can help fight coronavirus with software. I don’t know how yet, as I’m not in the medical software industry, and this is the point of sharing this post with you.

What software projects fight coronavirus?

What are the software projects that developers can contribute to, in order to fight coronavirus? Maybe…

• Epidemiology software, to analyse the spread?
• Genetics software, to better understand how the virus works?
• ICU software, to help doctors resuscitate people that are in bad condition?
• ER software, to handle the massive influx of people needing care?
• Any other software?

The above are just my layman’s assumptions, they’re probably incorrect and incomplete.

What I’m sure of though, is that some software projects matter out there, and that we’re thousands of developers that are able to advance those projects.

We’re representing a considerable workforce with our spare time, and also because I’m sure some companies will be happy to lend some working time of their developers in order to help them save lives, get us out of this weird period, and restore business as usual.

Healthcare professionals are actively fighting coronavirus, dedicating their lives to it. Most of them are helping individuals. We developers can help with our skills too, as software scales and impacts lots of people.

Help by sharing

As as see it, you have 3 options now:

Option 1: you know of a software project that helps fight coronavirus. Be it open source or proprietary, share it with us in the comments section below. And share this post (Twitter, Reddit, HN, LinkedIn, FB, email your colleagues…) so that more people can contribute.

Option 2: you don’t know any software that helps fight coronavirus but you also believe that developers can help. Share this post (Twitter, Reddit, HN, LinkedIn, FB, email your colleagues…) so that it reaches people working on those projects.

Option 3: you don’t think developers can make a significant change in the coronavirus situation. Then wash your hands and stay away from people!

In solidarity with all the cancelled C++ events, and since we’re all focused on adjusting to protect ourselves and our families, there won’t be posts on Fluent C++ for a few days (Patrons continue to receive their ebooks and articles though). And also because I want you to come back to this post and check how the comments section grows. Better yet, subscribe to the comments in the discussion, by clicking the Subscribe button at the bottom left of the comments thread.

On Twitter, use the #CodeAgainstCOVID19 hashtag.

This is the first time most of us see such a thing in our life. The world is shutting down. Let’s do what we do best to help save it: code.

The post How Can Developers Help Fight Coronavirus? appeared first on Fluent C++.