Understanding large code

Question

The question of understanding a large code has previously been well answered. But I feel I should ask this question again to ask the problems I have been facing.

I have just started a student job. I am a beginner programmer and just learned about classes two months back. At the job though, I have been handed a code that is part of a big software. I understand what that code is supposed to do (to read a file). But after spending a few weeks trying to understand the code and modify it to achieve our desired results, I have come to the conclusion that I need to understand each line of that code. The code is about 1300 lines.

Now when i start reading the code, I find that, for example, a variable is defined as:

VarType VarName

Now VarType is not a type like int or float. It is a user defined type so i have to go the class to see what this type is.

In the next line, I see a function being called, like points.interpolate(x); Now i have to go into another class and see what the interpolate function does.

This happens a lot which means even if I try to understand a small part of the code, I have to go to 3 or 4 different classes and keep them in mind all at one time without losing the main objective and that is tough.

I may not be a skilled programmer but I want to be able to do this. Can I have some suggestions how i should approach this?

Also (I will sound really stupid when I ask this) what is a debugger? I hope this gives you an idea of where I stand (and the need to ask this question again). :(

Answer 1

With any luck, those functions and classes should have at least some documentation to describe what they do. You do not need to do know how they work to understand what they do. When you see the use of interpolate, don't start looking at how it works, otherwise you end up in a deep depth-first-search through the code base. Instead, read its documentation, and that should tell you everything you need to know to understand the code that uses it.

If there is no documentation, I feel for you. I can suggest two tips:

1. Make general assumptions about what a function or class will do from its name, return type and arguments and the surrounding code that uses it until something happens that contradicts those assumptions. I can make a pretty good guess about what interpolate does without reading how it works. This only works when the names of the functions or classes are sufficiently self-documenting.

2. If you need a deep understanding of how some code works, start from the bottom and work upwards. Doing this means that you won't end up having to remember where you were in some high level code as you search through the code base. Get a good understanding of the low level fundamental classes before you attempt to understand the high level application of those types.

   This also means that you will understand the functions and classes in a generic sense, rather than in the context of the code that led you to them. When you find points.interpolate(x), instead of wondering what interpolate does to these specific points with this specific x argument, find out what it does in general. Later, you will be able to apply your new-found knowledge to any code that uses the same function.

Nonetheless, I wouldn't worry about 1300 lines of code. That's basically a small project. It's only larger than examples and college assignments. If you take these tips into account, that amount of code should be easily manageable.

---

A debugger is a program that helps you debug your code. Common features of debuggers allow you to step through your code line-by-line and watch as the values of variables change. You can also set up breakpoints in your code that are of interest and the debugger will let you know when it's hit them. Some debuggers even let you change code while executing. There are many different debuggers that all have different sets of features.

Answer 2

Try making assumptions about what the code does based on its title. For example, assume that the interpolate function correctly interpolates your point; only go digging in that bit of code if the output looks suspicious.

Answer 3

First, consider getting an editor/IDE that has the following features:

• parens/brackets/braces matching
• collapsing/uncollapsing of blocks of code between curly braces
• type highlighting (in tooltips)
• macro expansion (in tooltips or in a separate window/panel)
• function prototype expansion (in tooltips or in a separate window/panel)
• quick navigation to types, functions and classes and back
• opening the same file in multiple windows/panels at different positions
• search for all mentions/uses of a specific type, variable, function or class and presentation of that as a list
• call tree/graph construction/navigation
• regex search in addition to simple search
• bookmarks?

Source Insight is one of such tools. There must be others.

Second, consider annotating the code as you go through it. While doing this, note (write down) the following:

• invariants (what's always true or must always be true)
• assumptions (what may not be true, e.g. missing checks/validations or unwarranted expectations), think "what if"
• objectives (the what) of a piece of code
• peculiarities/details of implementation (the how; e.g. whether exceptions are thrown and which, which error codes are returned and when)
• a simplified call tree/graph to see the code flow
• do the same for data flow

Draw diagrams (in ASCII or on paper/board); I sometimes photograph my papers or the board. Specifically, draw block diagrams and state machines.

Work with code at different levels of abstraction/detail. Zoom in to see the details, zoom out to see the structure. Collapse/uncollapse blocks of code and branches of the call tree/graph.

Also, have a checklist of what you are going to do. Check the items you've done. Add more as necessary. Assign priorities to work items, if it's appropriate.

---

A debugger is a program that lets you execute your program step by step and examine its state (variables). It also lets you modify the state and that may be useful at times too.

You may use a debugger to understand your code if you're not very well familiar with it or with the programming language.

Another thing that may come in handy is writing tests or input data test sets for your program. They may reveal problems and limitations in terms of logic and performance.

---

Also, don't neglect documentation and people! If there's something or someone that can give you more information about the project/code, use that something or someone. Ask for advice.

---

I know this sounds like a lot, but you'll end up doing some of this at some point anyway. Just wait for a big enough project. :)

Answer 4

You may basically needs to understand what is the functionality of a function being called at first, then understand what is input and output to that function, for example, if you really needs to understand how interpolate is done, you can then go to the details. Usually, the name of the functions are self-explainable, you can get a feeling about what the function does from its name if the code is well written.

Another thing you may want to try is to run some toy examples to go through the code, you can use some of the debuggers or IDE that can help you navigate through the code. Understanding large-scale code takes time and experience, just be patience.

Answer 5

"Try the Debugger Approach"

[Update : A debugger is a special program that lets you pause a running program to examine the state of program (Variable Values/Which function is running/Who is the parent function etc.,)]

The way I do it is by Step Debugging the code, for the usecase I want to understand.

If you are using an Advanced/Mordern IDE then setting breakpoints at the entry point (like main() or a point of interest) is fairly easy. And from there on just enter into the function you want to examine or overstep the function.

To give you a step by step approach

1. Setup a break point in the main() methods (entry points) starting expression.
2. Run the program with debugging active
3. The program will break at the break point.
4. Now, if step over until you come across a function/expression that seems interesting. (say, your points.interpolate(x); ) function
5. Step into the function, and examine the program state like the variables and function stack, in live.
6. Avoid complex system Libraries. Just Step over/Step out. (Example: Avoid something like MathLib.boringComputaion() )
7. Repeat until the program exits.

I found out that this way of learning is very rapid and gives you a quick understanding of any complex/large piece of software.

Use Eclipse, or if you cant then try GDB if its C/C++. Every popular programming language has a decent Debugger.

Understand the basic debugging operations like will be a benifit:

1. Setting-up a breakpoint.
2. Stopping at a breakpoint.
3. Examine/Watch Variables.
4. Examine Function Stack (the hierarchy of function calls)
5. Single-Step - Stepping to next Line in Code.
6. Step-Into a function.
7. Step-Out of a function.
8. Step-over a function.
9. Jumping to the next breakpoint (point of interest).

Hope, it helps!

Answer 6

Many great answer have already been given. I thought to add my understanding as a former student (not too long ago) and what I learned to help me understand code. This particularly helped me because I began a project to convert a database I wrote in Java many years ago to c++.

1. **Code Reading** - Do not underestimate this important task.  The ability to write code  
   does not always translate into the ability to read it -- and reading it can be more 
   frustrating than writing it.

Take your time and carefully discover what each line of the codes does. This will certainly help you avoid making assumptions unless you come across code that you are familiar with and can gloss over it.

2. Don't hesitate to follow references, locate declarations, and uncover definitions of 
   code elements you are reading. What you learn about how a particular variable, 
   method call, or class are defined all contribute to learning and ultimately to you 
   being able to perform your task. 

This is particularly important because detective, and effective detective work, are essential parts of being bale to understand the small parts of the code so that you can, in the future, grasp the larger parts with less difficulty.

Others have already posted information about what a debugger is and you will find it is an invaluable asset at tracking down code errors and, I think, helps with code reading, knowledge gain, and understanding so you can be a successful programmer.

Here is a link to a debugger tutorial utilizing Visual Studio and may give you a strong understanding of at least the process at hand.