Ask HN: How to get better at reading source code? | Hacker News Reader

Ask HN: How to get better at reading source code?

8 pointskevinburke6 comments

I've got a 2500 line Python file I'd like to understand thoroughly. Here are some questions I have:

Where should I start?

What questions should I ask the code's maintainer, if she is a busy person?

I've been using grep to search for places where methods from this class have been called from other classes; is there a better tool?

Are there any formal resources that teach you how to read/understand someone else's source code?

It's just been going really slow and I wonder if there are ways I could be understanding faster.

View on HN

You don't mention whether you can run the code, whether it works as intended and your experience level vs. the authors'.

I've never seen any formal resources and progress will be really slow at first but will accelerate as you keep chipping away at it.

I've found that commenting sections with explanations and questions helps. Sometimes I rename variables with names that make more sense to me.

If the code is very idiomatic it helps to understand why things are done a certain way. I look at a lot of vendor libraries that are poorly written and sometimes it easy to assume that because it comes from someone else it's written in a smarter way, when the opposite is true.

I work mostly in statically typed languages that allow creating call trees - not sure if that's workable for Python or not - but there may be tools more advanced than simple grep.

At the risk of sounding uncool, if I was stuck I would flow-chart the gosh-darned thing.

I once did this for an engineering subsystem with more than 10,000 lines of FORTRAN. It took me more than a month. We were relocating a flight simulator from Italy to Spain where it would go through testing and customer acceptance before being put back in service.

By the time I was done, I could debug the system almost as if I had written it myself. It made me look like a freaking genius.

The point is _not_ about flowcharts being wonderful. It just forces you to trace the path of execution through the code, and figure out what each bit is trying to do. The tangible documentation (i.e.: stack of flowcharts) that you end up with is great for building your confidence, and convincing your boss that progress has been made.

You mean manually create them? Or is there a generator tool you could suggest?

Yes, I mean manually create them.

Again, the flowcharts themselves are completely useless when you're finished. It's the process of preparing them that forces you to start digging through that little mountain of code.

My personal preferred strategy is to try and understand some of the important call sequences. So something you might like to try is to put some trace at the start of every function in the file. Whilst you are doing this, look for callbacks that are being passed into the class as parameters, and put trace in any of those that you find too.

Now, run the application/process, and see which functions are called in response to which actions. You may not see all of the functionality, but this will show you at least a few of the key parts, such as initialisation, and hopefully a few of the nominal use cases.

I recently had to take over a few thousand lines of code, spread over 5-10 files. Really, what works for me is following the code from start to finish, and a very high level. Basically, mapping the order every function is called and getting a quick idea of what that function does. Many times the function name alone is enough. From there, you know where to look when you want to understand some specific functionality in depth.

Reply on news.ycombinator.com