Dealing Sympathetically with Legacy Code

  /     /   Legacy Code     Programming     Retro    

I have often noticed programmers getting worked up about the legacy code they are maintaining. I know it is annoying having to wade through poor code, or worrying about making changes for fear of unexpected side-effects. However, it is important to see the code for what it is and in the context of when it was written. Coding styles change, programmers change. What a programmer did then, they may not do today. Once this is accepted, I find the code base is accepted.

What is legacy code?

I define legacy code as code that is no longer maintained, or that is frightening to work on because it not fully understood. Typically this code has no tests and is hard to test because it hasn't been written to be tested.

Preparing the environment

Before you can work effectively with the code, you need to ensure the environment is conducive. This can be a big hurdle if the build tools or environments themselves are outdated or poorly understood. I have repeatedly come across poor build automation so that builds took longer and were more complicated than should have been the case. Improving this can make a huge difference to the speed with which you can make a change and test it.

Exploring the code base

To make changes to the code you need to take the time to explore and properly understand it. Do this by adding temporary comments, refactoring, adding tests and using your revision control software to create branches where you can take the code apart and test your understanding.

Making style changes

Coding styles do change and every programmer has their own preference. Don't be too critical of coding styles that were typical when the code was written and don't judge the code by today's standards. Try to fit in with the coding style of a file. A mixture of styles in a file can be very confusing and makes it much harder to work with. If you feel that you can't adapt to the style, then change it throughout the file or start the new style in a separate file. When you do make style changes, try to put them in a separate commit, so functional changes and style changes are distinct. This helps future maintainers of the code.

Elements of coding styles that you may want to consider seriously before changing include: tabs vs spaces, camel caps vs snake case, K&R declarations vs prototypes, procedural vs object-orientated paradigm.

Comments lie

Comments can be useful to explain complex code or dependencies. However, they are often out of step with the code and therefore can confuse. Think seriously before putting comments in code. I often use them as I am exploring code to understand it. Once I have gained the understanding that I was looking for, I will refactor the code and remove virtually all the comments. Less is more as far as comments go.

Refactoring

Rather than using comments to explain code, I would much rather refactor the code so that the variables and functions make it clear what is happening. Functions can be tested and maintained more easily and if your understanding of the code changes, you are more likely to change the functions to suit, this may not be the case with comments. For more on this take a look at: Refactoring: Arm Yourself in the War Against Useless Comments.

Testing

Adding tests to code can be the most useful change that you make. It will often feel difficult if the code wasn't designed to be tested, but will reap rewards in terms of understanding and confidence in the code. Think of good tests as a gift to yourself and those that maintain the code after you.

Remember the next guy

Any changes that you make should improve the maintainability of the code not add to the technical debt. You may not be the last person to work on this code, so please remember the next guy.

Creative Commons License
Dealing Sympathetically with Legacy Code by Lawrence Woodman is licensed under a Creative Commons Attribution 4.0 International License.

Share This Post

Feedback/Discuss

Sign up to get new articles straight to your inbox.

Delivered by FeedBurner

Related Articles

Position Independent Code (6502) on the Commodore VIC-20

If we are writing 6502 machine code and want to to create a routine or program that can be placed in any location then we have to create Position Independent Code (PIC) or make the code relocatable. H...   Read More

Adding Basic Stubs to Assembly Language on the Commodore VIC-20

To make machine language programs more friendly it's nice to add a Basic stub which contains a line with a SYS statement to start the code. This is easy to do on the VIC-20 and the process gives you a...   Read More

Hand Assembling to Machine Code on the Commodore VIC-20

I quite enjoy designing machine language routines on paper and then hand assembling them. For many people this would have been their only option until they got a more advanced machine language monitor...   Read More

6502 Machine Language Tables and Aids

When programming using machine code there are a few useful aids that can make it easier to do. I have created a couple of tables for the 6502 that can make the process easier. They are based on table...   Read More

Tokenize/De-tokenize Commodore Basic Programs Using petcat

petcat is a utility provided with the VICE Commodore emulator that you can use to convert Basic source code contained in ASCII text files to .PRG files or vice versa. It is also able to convert ASCII ...   Read More