What are the skills needed to read and understand other people's code?

Question

Hi,

I have got a new job, and in this job I need to go through other people's code to understand the application.

• What are the skills which I must acquire to accomplish the task of reading and understanding other people's code?
• What best-practices should I follow while reading and understanding other people's code?
• Which books or online resources are relevant to this task?

Thanks.

Answer 1

The best advice here is just to practice it lots - you need to know not just the basics of the language, but all the different approaches others can take.

Advice:

1. Figure out a component you want to understand.
2. Look at the small pieces you need to understand, to understand that component.
3. Understand those pieces, and /write extra comments to explain those pieces/.
4. Repeat (3), then repeat (2), until you succeed with (1).

Answer 2

There are really no books that I know of that will help you, but, it does require you to try to understand their method of programming.

So, if your company has a programming standards reference, that would be useful to understand.

When I am reading someone's code I find it easiest to just start at the beginning, where is the main of the application, then start to just go through, with various inputs.

If they don't have many unit tests, then you could just start to write some unit tests, and that will help you to not only understand the code, but to do something that can be very useful in the process.

Once you have started from the main you will find paths that you can take, just pick some part that is interesting, and continue to do the unit tests for that part.

If they have unit tests, then read those while looking at the section, as the unit test should tell you what is expected to happen when certain good or bad inputs are sent.

Answer 3

First, start with the language. What language or languages are you going to have to read?

Next, go to O'Reilly's website and get some books on those languages, or search Amazon.com for literature on those languages.

Read, learn.

Now if you want to learn how to program, rather than to learn the languages... well that's a different set of books and lots of practice :)

Answer 4

I recommend trying to actually implement small throwaway programs based on what you are learning. At first you will have to constantly go back and forth between the original reference material in order to get things working. The more you actually practice by doing though, the easier it will get. There is no substitution for actually coding. Reading books and other peoples code is good as reinforcement to this practice.

Once you start advancing I recommend looking at open source projects. There is a large volume of code to look through, and many styles at work.

Answer 5

If you don't have much experience as a software developer, you can read Code Reading: The Open Source Perspective for some insights.

And sometimes while you'll trying to understand a new code base, Don't Be Afraid to Break Stuff.

Answer 6

An OPEN mind to others' solutions is highly desirable.

Reading and understanding is more difficult if you get hung up on 'I wouldn't have done that way'.

Answer 7

I agree with what other people have said: you just have to do it.

My third job as a programmer involved fixing and modifying code other people had written, in a (circa 1989-1991) huge code base of about two million lines of C. I hated it, and it was an invaluable teaching experience that I have come to appreciate enormously. In a way, that's been the foundation of my entire programming career in the 18 years since.

You might take a look Working Effectively with Legacy Code, by Michael Feathers. It might be helpful to you - I haven't read it myself, but it's on my wish list, and I've heard great things about it.

Answer 8

When I get lost in a code base, I generally choose some bite size pieces of functionality and trace through them. A debugger or trace statements will be your friends. Once I have a good idea of the flow through the code, then I dig into the details and read it.

Rinse and repeat. There's no substitute for time spent in a code base.

If the app is well structured and well written then the approach above will be overkill.

Answer 9

• Others are right, you need to have a firm grasp of the language you are working in.

• You also should spend some time getting familiar with the domain you will be working in, if you are not familiar already. Learn the key concepts and terminology (or range of terminology). In some jobs I've had, this has taken years master, due to the technical nature of it.

• Practice, practice, practice. The more code you read, the faster you will be at it.

• Get a good IDE when you are learning new code. It will allow you to follow the thread of execution by clicking through method calls to see what they do. This will be invaluable.

• When you really need to understand the code, and it is complex, writing some tests is invaluable. It helps you understand the possibly complex behavior, as well has being useful moving forward when you need to modify it.

• If you really have to understand code, and it is hard to understand, it may be worth to modify it in the editor-- rename variables so they make more sense to you, etc. Some people learn better experientially.

• If there are good documents that provide overviews of the system, start there. Only if they are good, though.

• Ask other questions to your teammates, if you have the ability to do so. Someone experienced with the code can jumpstart you.

• Unfortunately, often comments in the code aren't much help, as they can often be out of date. It may be useful to remove the comments (or just ignore them).

Good luck!

Answer 10

• Get an overview of the domain and the application
• Determine the naming convention used in the code
• If there are patterns or frameworks in use, detect them via from code comments or code naming conventions, learn the related patterns and frameworks
• Obtain a tool to reverse engineer Sequence Diagrams (e.g Altova)
• Reverse engineer the application into an UML model
• Reverse engineer the database, if applicable
• Figure out "center of gravity" of the application, I mean, seperate the "noise" (utility sort of artifacts) from "core" - dependency (includes or imports), generalization (extensions or implementation)
• Understand logic stored in database
• Good luck with javascript code
• If you are working on large COBOL, RPG, VAX-Pascal/C/C++, BASIC, FORTRAN, or other such codebase, quit unless you are making $150K to $200K

Answer 11

Practice! Has to be skill number one.

Then after that, maybe cross-referencing with books or other information related to the code you are reading. But that is way down the list. Practice is at least the top 4 spots on the list.

80% practice. 20% supplementation with related learning materials.

Answer 12

My suggestion is to deconstruct what you want into a few buckets:

1. Conventions - Are there common themes in how variables are named or methods? Are there long methods or short methods? Are there comments in the code?
2. Testing - Are there tests that go along with the codebase?
3. Object Model - This doesn't always apply but sometimes it can be handy having an idea of what classes are used for what.
4. Bug tracking - Is there any tracking of bugs in this code?

Those would be my starting points in getting a handle on a new application.

Answer 13

Skills: patience and perseverance.

Best practices: I tend to fix formatting errors in code and grammatical errors in comments as I go through the code.

Resources: original programmer, users, Google.