Refactoring for Legacy software

Table of contents

Introduction

I have a lot of times to read or modify a legacy code at my company.
The code sometimes let me feel that I want to refactor because it has a bad design and is difficult for me to read.
I read the following book and studied a lot of things to refactor the legacy code.

レガシーソフトウェア改善ガイド

In this article, I'm introducing what I studied.

Start refactoring

• It is natural that we have a negative feeling for a legacy software, but it is very harmful. It clouds our judgement and prevent us to improve our work effectively.

• The best way to overcome fear of unknown is jumping in the code and starting playing around with it.

• It is important for us to ask myself, "how difference could we get by refactoring?"

• We need to choose one or more ways to measure a quality of code. By measuring the quality, we can get an simple index how the quality improved by refactoring.

• When a new member came to our team, we should ask him to measure how long it takes to get a latest version software and execute all of development tools on his local machine.

• When we choose a next refactoring target, it is useful for us to know which source file is edit most frequently in our project.

• An ideal system we hope is that it can supervise a quality of a code automatically and that all of members in the team can use the information.

Preparation for refactoring

• We always should execute refactoring with our team's goal in mind. In other words, we should not forget who pay your salary and execute the refactoring when we can prove the refactoring can bring a long term value for our business.

• One of important question we have to answer before starting a big improvement project is "Refactoring of Rewriting?"

• We need to get an agreement about what we achieve and our schedule from all of members of our team.

• Pair programming might be difficult until we get used to it. A traditionalist will dislike it but we have to understand it.

• Refactoring is originally a risky work. Every time a modification is add to the code, a bug will cause because of a human error.

• All of code is not equal. An code is more valuable than any other code or an code is more risky than any other code.

• It is important for us that we understand a balance between value and risk.

Code review

• Code review is an opportunity to share their knowledge for reviewers.

• A person who wrote the code can show what he wrote to any other members in his team.

Special event

• An event which is different from usual routine work is effective as stimulation of communication.

• A company has an event "Tech talk" which is held every 2 weeks. It takes for an hour and is held on Friday afternoon. Some developers can speak about a technology which is related with their work or is not related too.

Risk

• It is difficult for us to estimate a working time for a big refactoring project.

• In an existing software, all of specification of the system including all of rules for the business is encoded as a source code. If we could not prove that all of specification can be transplanted to the new system, the behavior of system would change as a result of refactoring or rewriting.

• Even if we chose rewriting finally, we should try refactoring at first. It is a good way of studying a code base and we can get a valuable insight about "what is the best design and implementation of an alternative system?"

Mikado Method

• By drawing "Dependency graph", we can execute the tasks in optimal order more safely.

Commented out code

• If you found a commented out code block, you can delete it without hesitation.

• There is no reason why you remain the commented out code.

• We should use a version management system to record how the code was modified.

Test

• standard of good test 1: in a condition or assumption(given)

• standard of good test 2: when this test is executed (when)

• standard of good test 3: a result should be like this(then)

• Originally, we should test a behavior which components propose each other and an internal state should not be tested.

• An good test is deterministic.

• For preparing an initial test, we need to lower our standard temporarily. We will refactor without any tests but it can be made up for by code review.

• If your refactoring affects multiple units, your refactoring will depreciate a value of your test.

• We can validate a code behavior which is written well and can be estimated by only code review.

Documentation

• After we decided how refactoring or rewriting is executed, we need to write about them in detail and explicitly in a document.

• All of people who is interacting with the project have to understand the document is "Single Source of Truth".

• How will we deal with the current implementation as a new implementation of a specification?

• If a document is put close to a source code, a developer can find it easily. Putting the document at same repository of the source code is recommended.

Construction of development environment

• A developer should be able to install all of dependency and execute it on his local machine.

• README file should be written simply. The contents includes an information that a new developer needs for starting his work.

• Vagrant: Tool to automate a process of virtual machine management.

• Ansible: Tool to automate a provisioning(an installation and a configuration of dependency).

• An outstanding developer master a tool which he use every day and he makes amazing result by using the most powerful function of the tool.

Keeping quality of code

• "A stitch in time saves nine"

• It is useful for us to plan a periodical code review.

• You should ask all of reviewers to see the code in advance and write a memo.

• You should ask one of reviewers who has a knowledge about codes to be a leader of the code review.

• The review should be done within 1 hour. If the time was not enough, you can hold multiple time sessions during a few weeks.

• A software should be designed like "disposable".

• A real value of "disposable software" is that we can start over without any risk by disposing a part of software.

• We should be proud of a code you wrote. If you were given a code any other people wrote, you should bring up the code in honor of it for predecessors and people who come later.

• We leave a legacy for a developer who will bear next generation, so we should make the legacy proud by doing something as much as possible.