Best Practices and Tips for Reading Source Code [closed]

Question

Code reading is an important part of a programmer's life because we usually work in groups and have to maintain, complete or contribute to the other developer's codes. From that point of view, code reading is inevitable. Our performance criteria is not only fast reading or interpreting. But also understanding and interpreting the code correctly is very important in our daily work-life. We usually have to deal with several different types of codes such as well documented ones, badly written, undocumented ones, buggy ones and even spaghetti ones. We usually have to deal with each one of them using different techniques and shortly my questions is how do you deal reading those codes, for instance consider dealing with undocumented and badly written codes.

For example I apply some small methods for C/C++ code:

• Find the dependencies of the code and try to figure out the general overview of inter-class or inter-function relationships. Visualise on paper or board if necessary.
• Try to understand the coding conventions they have used and get used to it.
• Understand the general purpose of the functions in a file (figure out why are they populated in that file).
• Start from the main and find the places that you may have to change if necessary.
• Do some small modifications and put print statements in strategic locations to understand what a function or class is doing.
• Use cscope

My question is do you have any these kind of tips, tricks or best practices that you'd like to share?

EDIT: Forgot to ask the question :)

Answer 1

Have a white board or a handwritten notepad available. I find it helps me understand the code as I jot down the data structures and how they are manipulated as I attempt to understand the problem. This is absolutely critical in algorithm bound code, but still helpful in business oriented database driven code as well.

Answer 2

Use and IDE to read the code, it will make a whole lot more sense than it would in notepad.

This may seem obvious but the best things usually are and as such are ignored.

Answer 3

A few tips I use:

• Review the unit tests
• Read header comments, but don't trust them, verify that the code does what it says by...
• Review the parameters, what do they represent and are the checked for bad data.
• Mentally step through the methods/functions with different inputs.
• Actually step through in a debugger, idealy driven by a unit test.
• If there a multiple return points in a method verify that you can see how to get to them all.
• If there are any "interesting" lines, e.g. an exception is thrown, a bit of debug info is logged then verify you can navigate your way to that and that you understand why it is being thrown/logged/whatever.
• Look for boundaries with other systems, e.g. if it gets data from a database what is getting and what happens if that fails, does it guard against bad data.

Answer 4

When I'm reading through new code, one thing that I always do is keep a note pad (or text file) open, and jot down stream-of-consciousness style all of the things that confuse or irritate me about the code (there are always some), along with the "aha" moments where I understand why something was done in a way that was initially confusing/irritating.

Once I'm done, I talk talk to someone who is familiar with the codebase and try to get a reason for all of the points of confusion/irritation on the list that don't have a corresponding "aha", and consider if they are candidates for refactoring, or else update my "aha" list.

Finally, I take the list and clean it up and add some structure, and then use it to create/append to a document that will hopefully be useful to other developers who are trying to get accustomed to the code base.

At my last job, I actually formalized this as part of the process that someone should do whenever they started working in a project or part of a codebase they were unfamiliar with, and we ended up having a nice wiki full of pointers on how to navigate the code base that ended up being very useful to new hires or team members jumping into other projects.

Answer 5

Print it and then trace it with a pencil.

I did this when I was a co-op student who had to add two features to a particularly hairy Excel VBA application. After I fulfilled the requirements (and refactored the hell out of it), they told me that the original author had given up on it after coding himself into a corner.

Answer 6

My tip: Use IDE to run code step by step in debug mode, or use breakpoints.

I use Eclipse to run code step by step in debug mode.

Answer 7

The most important thing I learned rather late was: use the debugger. All the time. Even if it has been mentioned twice or more, it's really important. You can see where functions are called, who calls them and so on. If you see comments in code: Don't believe them. Always check, if the comment really says what the function does. Sometimes they do not match and you'll get lost in wrong assumptions.

Answer 8

Enterprise Architect can generate various kinds of UML diagrams from source code (even behavioral diagrams via debugging). It is a really powerful weapon against cowboy-coded programs.

Answer 9

We use our own computer language expert system to extract, from the code, demographic and architectural information. We have off-the-shelf rules to produce a number of dependency analyses (module/function cross-reference, calling tree, and include/COPY tree, all in both directions), as well as global data name cross-reference (also in both directions). Then, as we begin to get the lay of the land, we whip up rules to do ad hoc analyses, to address questions that arise about what the code is doing.

We use the same automation approach to automatically improve the code's quality (structuring to eliminate goto's, decompiling low-level stuff, etc.), which makes the code easier to understand. Ditto for changing unfortunate names of data, classes, methods, functions, etc. to more meaningful versions. Ditto for imposing consistent coding standards and conventions, to further improve readability.