
Ask HN: How to get better at reading source code? - kevinburke
I've got a 2500 line Python file I'd like to understand thoroughly. Here are some questions I have:<p>Where should I start?<p>What questions should I ask the code's maintainer, if she is a busy person?<p>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?<p>Are there any formal resources that teach you how to read/understand someone else's source code?<p>It's just been going really slow and I wonder if there are ways I could be understanding faster.
======
zwieback
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.

------
phugoid
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.

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

~~~
phugoid
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.

------
demallien
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.

------
dsmithn
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.

