When coding we often spend a significant amount of their time understanding new or unfamiliar code. Attempting to use a new library or fix a bug in a poorly organized component without first fully understanding the code we are working with can cause  headaches. Complex code can often be better understood through the use of diagramming tools (discussed here). However diagrams and other documentation cannot exist in a vacuum and there are tricks to better understand your code before attempting to diagram it.

As a novice developer I often attempted to dive straight into unfamiliar code to find the portion that was applicable to my project. This led to a number of situations where my lack of knowledge about the code base resulted in bugs or significant delays. Now, when i am first confronted with code that I cannot immediately decipher I make sure to take a step back and understand it using all the tools at my disposal.

Talk to co-workers: There is no better way than having a source of information that describes the main concepts in a codebase. If you can find someone to help you, take a pen and paper, go to him and take lots of notes. How much should you bug the other person? In the beginning – as much as is practical for your work, but no amount is too little.

Find documentation: Most projects already have some documentation lying around. Yes, it is often out-of-date – but when trying to start working on a project some documentation is better than none. At the very least the documentation should help you to figure out some of the main concepts in a project and act as good starting points.

Think about tools: If you are new to a part of a project – you are going to be spending a significant amount of time understanding the code, so see how much help you can get automatically. There are good tools and bad tools. Try to figure out which tools have capabilities that might be helpful for you first. Many UML tools are intended to be helpful during the design phase and therefore may not be ideal for understanding tasks. Make sure to investigate the features of tools carefully to determine if they are a good fit.

Time vs cost: Sure, free is great. But if a free tool is not being used by many people – it might be that the tool does not work. There are many tools that are created just as an exploration of what could be done, but are not really helpful and therefore just made available for free in hopes that someone else will adopt it. Another way to think about it, is to decide how much your time is worth – it might make sense to spend a day or two to get a tool that works for you.

Use your brain: There is no substitute to actually trying to understand a code base from the bottom up. You might need to take down notes and refer back to them later. Can tools help? Definitely. But don’t expect them to do all of the work for you.

Thinking about these points before diving into unfamiliar waters could get you moving much faster. Are there any other tips that you have found helpful in understanding a new codebases faster and easier?

I am writing new articles once every 2-3 months. Interested in getting notified? Sign up here.