Author: Sotiris Fanou
Many software development teams jump directly to implementation skipping design. This practice produces inflexible code with no structure, which is difficult to change and maintain. For example, if someone wants to fix a bug or add a new feature it is like trying to reach an unknown destination without a map. It is very difficult to know where to change the code and if this will be affecting something else elsewhere. Additionally, numerous programmers disregard the readability of the code they write. One reason could be the fact that most developers work within tight schedules and their priority is to finish by the deadline rather than write clean code. Unfortunately, many programmers think that if their code is unreadable this will be a problem for someone else in the future and it will not affect them. Therefore, a lot of code out there is not structured, difficult to read and difficult to be amended and maintained.
Very few developers work on creating brand new software systems. Typically programmers spend most of their time enhancing or debugging existing software systems. The software engineering literature supports that at least 80% of the programmers’ time is spend on maintenance. This means working with existing, older code. Sometimes, developers may be lucky enough to have to add a new feature to an older system. In this case, as in debugging, first they have to understand the existing code and its structure, and then incorporate the new requirement at the proper place. If the existing code is not structured and difficult to read, then a programmer will waste more time to understand it and figure out where to add his or hers. Even the best programmers are rendered inefficient if the code is unreadable and unorganized.
As unorganized and unreadable code has been one of the most difficult and persistent problems which I faced in my career I decided to investigate it and if possible device a plan to mitigate it. My intention was not to learn or teach others how to write cleaner or readable code. There are plenty of Web articles and books on this subject but those books are helpful when the developer is writing new code. The problem I wanted to tackle was a method to work with existing bad written code and how to make it more readable.
The best solution would of course be to refactor it with the purpose of adding design, structure and to make it more readable, but that is costly in terms of work hours and it requires a whole new commitment. The solution which I propose below is less costly than refactoring. My solution lies somewhere between leaving the code as is, and completely changing it by refactoring it. Leaving the code as is means that many developers will be wasting extra hours trying to understand it. Refactoring it also means that some developers will spend many hours in order to re-write it. The solution which I devised takes an in between approach. It costs less in work hours but it is not as good as refactoring. It is an in between solution which can be applied when refactoring is not possible.
The method I am suggesting has been tested when I was working as team lead in a US company, and it proved to be effective. The team was assigned a project where we had to add new features to an old program. The existing code was badly written, with no design, no code comments at all, no documentation and none of the original programmers around for us to ask questions. The developers of my team were complaining that they were spending many hours trying to understand the existing code. This was necessary in order to add the new features to it. I also knew that different developers would have to go over the same parts of this badly written code again and again.
I suggested the following solution to them. First, they should add comments to any part of the old code they worked on. This would make things easier for the next programmer who would also have to work on the same part of the code. I did not want them to overdo it and fill the code with redundant comments so I had to give them a tutorial on how to comment properly based on a chapter from the book “Clean Code” by R. C. Martin [1].
The Integrated Development Environment (IDE) which we were using then, did not support annotation, therefore, I also instructed them to add their name or initials at the appropriate places so that the next developer could see who went over a specific part of code. This way the following programmers could ask the previous developer questions as s/he already worked on and probably even refactored that part of the code. This was a temporary aid. When the project finished we removed the developers’ names from the comments.
Another suggestion was, to refactor certain parts of code, as long as this would not take very long. These were parts which would be used by other programmers for the purposes of our project. They could also make other minor changes for the goal of making the code cleaner and easier to understand. For example, the developers could change a function or variable name in order to make it more descriptive. Our IDE could replace function and variable names globally and this was very helpful with this type of refactoring. Local changes to the code were of course easier and safer.
The solution worked. After someone went over a piece of existing code for the first time, by adding comments/documentation and by doing a little refactoring, the specific part of code became easier to understand for the next programmer who had to use it. Also when a developer was working on a specific part of code, he could see who worked on it before him and so he could consult the first developer. After a few months of work on the old system, the developers reported that the parts of the code for which our team was interested in became cleaner and easier to understand. I used the same method since then a couple of times and it always improves the readability of at least specific parts of the code which our team is interested in.
Many of today’s IDEs support annotation therefore if you are going to use this method you do not have to write the programmer’s name in the code comments. Sometimes you are not allowed or should not touch existing code, e.g. build in libraries. To use this methodology you must be sure that you are allowed to change the existing code.
[1] Martin C. R., “Clean Code: A Handbook of Agile Software Craftmanship.” Pearson Education, Inc., Boston MA, 1996