Getting Started With Existing Code

Software developers often have to work with existing code bases, whether it's for joining an ongoing development effort or for maintenance work on a legacy application. Getting familiar with foreign code takes time and can be a frustrating experience. In this article I'm going to describe my strategies for getting up to speed quickly.

Gather Information

First of all, get in touch with the people who know the system best. Especially those who originally designed and built it can often provide interesting insights as can people from IT or operations. Be communicative: Don't waste your time struggling endlessly, ask for their advice on what's important and what is not.

Make a list of all the information that's available for the given system and find out what's outdated and what is still relevant. The information you typically need includes original visions, business concepts, use cases, and presentations, as well as technical documents describing the architecture, subsystems, used patterns, or even key algorithms. Documentation may reside on file servers, wikis, source code repositories, internal content management systems, or just as printouts on paper. Try to get a comprehensive list.

Use a Top-Down Approach

Learn the system's business domain, make yourself familiar with the overall architecture and have a look at how the domain's concepts map to the software. Try to understand the general idea that's behind the system and the kinds of problems it was designed to solve. Often that's particularly difficult to extract from documentation. The most valuable information is usually in other people's heads, so get them to share it with you.

Get a good understanding of the system's environment: The kind of hardware it runs on, the number of users it services, the amount of data it produces etc. Get an overview of the most important libraries and frameworks the system uses. Usually it's extremely helpful to understand its UI (if there is any) and its interfaces to other systems to see which services it provides and consumes.

As soon as you have worked through the high level architectural stuff, it's time to check out the source code from whatever repository there is.

Get the Code Running

Set up a working development environment and make yourself familiar with the build system. Especially for older systems this can be surprisingly difficult: You might have to dig out ancient development tools because the newer ones are incompatible. Ask for assistance when you need it, it's easy to waste a lot of time there. Make sure to document everything to save future team members the time and hassle.

Find out how to test the system. Go the whole way from running the test suite (if there is any) up to an end-to-end integration test. If there are databases or other dependencies in the development or testing environment see if they are still up to date. This is extremely important: If you fix a bug later, you need to be confident that the system still works and that you didn't break anything in the process.

When maintaining legacy systems it's often necessary to create a new release quickly after bugs have been fixed. Make yourself familiar with the release process, from both the technical and the organizational perspective and find out how the system's deployment works. That'll save you from nasty surprises when short response times are needed.

If your job is maintenance, you have to be able to react quickly to service requests or bug reports. First hand information is valuable, so try to get accounts for the production environment if possible. Access to log files and databases is very helpful as the operations or IT staff doesn't always provide all the information you need.

Read the Code (Some of It)

Up to now I haven't talked much about reading the actual code. That's no coincidence because I think there's not too much to gain, especially in maintenance of legacy systems. Even for small code bases it's hardly feasible to go through the code and understand it all, line by line. That would usually just be a waste of time. Problems will likely turn up in areas you've never seen, so concentrate your efforts on understanding the organization of the code and a few selected key areas.

Often it's helpful to pick a single interesting use case and trace it through the system at source level. Draw a few diagrams and ask your colleagues if they make sense. That way you'll get a feeling for the architecture and implementation. At the same time you learn the coding style and conventions.

In an ongoing development project you'll get down to coding soon enough. Writing a few test cases is a great help for getting familiar with the internal APIs. As soon as you feel comfortable (or maybe a bit sooner) get a few smaller assignments to dive in a bit deeper and read the related code as you go. It's far more efficient than spending lots of time browsing through code at the beginning.

Share Your Knowledge

Getting into an existing project can be highly interesting: There is a lot to be learned even from the worst and most obfuscated applications out there. If documentation is bad you will probably need a fair amount of help from your colleagues. Don't let it discourage you, instead make sure to write down your findings and use your fresh perspective to improve things. The next developer to go your way will love you for it.

social