June 30th 2016 by Fernando Zamora
June 30th 2016 by Fernando Zamora
For every programmer out there creating brand new code and working on the latest technology, there are many of us who are cutting our way through the code maintenance jungle.
Maintaining code is not for everyone. Some programmers love creating brand new code and introducing new technologies. We need those programmers in order to move companies and coding technologies forward. At the same time all projects eventually require maintenance. That’s where we need programmers that will do the dirty work of maintaining code and if they love it it’s even better.
Maintenance can mean a lot of different things. Maintenance can sometimes mean fixing defects. Other times it can mean enhancements. Sometimes it can mean refactoring and paying off technical debt. Or as in my latest case modifying the code to meet new technical requirements. Maintenance is not totally exclusive from creating brand new code. Maintenance sometimes means moving from the old to the new.
Suffice it to say that this problem has been on my mind for the last year or so and it has become one of my personal goals to get rid of the applet altogether.
Understanding Existing Functionality
Whenever we approach any maintenance problem, including this one, there are two things that must take place. First, we must truly understand the problem. That means we must not only understand the symptoms provided to us but also the original intent of the system. Once we understand that, we must truly understand the architectural structure providing the existing functionality. Knowing these two things ensures us that we provide a correct solution and that we don’t break functionality.
In this particular case our goal was not to fix a bug. Our goal was to replace the applet entirely. So in order to begin understanding the problem, we could turn to existing manuals, technical specs, functional specs and our existing business analysts. All these things get you a good part of the distance but not the entire distance. Not to mention that we don’t have the technical or functional specs. To truly understand it we must go behind the scenes and look at the actual code.
I can’t speak for everyone else but my brain can only hold about three things before I start losing track of what does what. This means that I can walk the code and if that code has more than three classes, three functions, three whatever I can’t keep track. As a side bar there is some discussion in the science arena that says that magic number that the human mind can manage is seven and now scientists have discovered that it could actually be closer to four. So it is extremely hard to keep all those code structures in my head and make sense of them.
Class Diagrams to the Rescue
When I first started looking at the source code for the applet, it looked quite daunting. I mean this thing has applets and a tree control. It has drag start and drag finish events. It has events to determine what is draggable and what is droppable. The only applet experience I have is from my college days almost twenty years ago and it consists mostly of drawing on the canvas and handling button events, not tree controls and Java GUI libraries. The code also has some tight coupling between all the different classes involved as well as some blurred lines of responsibility.
When looking at code it’s hard to see the forest for the trees. So…sometimes we need to take a step back and look from a higher perspective. Most of us are visual learners. It is easier for us to understand concepts and relationships if we can visualize them as actual things. For representing Object Oriented software visually it doesn’t get much better than UML Class Diagrams.
Below is sample of the diagrams that I drew based on the code. It might seem counter productive or extremely time consuming to read code and produce UML from it. But I will argue: “counter productive and time consuming as compared to what?”. I agree that reading code and understanding code takes time, but it takes even much longer without some recorded diagrams. It took me a couple of days to lay out the diagrams but as time went on the architecture became clearer.
So if you ever find yourself in a big mountain of legacy code consider UML class diagrams, they can be a great tool.