

Ask HN: Advice on Reading Source Code - nsomaru

I am a newbie programmer looking to improve my [Python] skills by reading some code (probably Django).<p>Every time I have sat down to do this I have felt overwhelmed by not knowing where to start.<p>Does anyone have advice on how and where to start reading source code?
======
sj4nz
Read the source with a question in mind. For example, how does some software
create a particular kind of file? (I did this recently for Pandoc's EPUB
writer-- while this software is in Haskell and not Python, the same rules
apply.) Do lots of searches for keywords that seem appropriate to your
question. When you find a class or function, trace its execution until you
understand it. Learn the difference between function calls and function
definitions--hopefully the formatting of the source makes a distinction. [For
example, in JavaScript, Douglas Crockford recommends whitespace hints for
functions, "function name () {}" would be a definition and "function name();"
would be a call. The space between the name and the '(' is the clue for the
difference. This is not part of the JavaScript language per-se.]

Write down other questions or make notes about anything you don't understand.
With most source, there's almost never any "best place" to start unless you
have a question in mind. I don't think anyone can read source like a novel,
because it is not a linear narrative--it is much more like a choose-your-own-
adventure book. The longer you read and skim the source code of any system,
you'll find that you know "where everything is" and just like a choose-your-
own-adventure book, you'll slowly internalize when it tells you to turn to
page 78 that the dragon is going to eat you without needing to turn and read
that page.

~~~
nsomaru
Thanks for your reply, I just hope I manage to escape the dragons and save the
heroine ;)

Do you use a simple pen-paper method for taking notes? How do you keep it all
together?

~~~
sj4nz
I do like paper, its very reliable with WiFi signals and very efficient with
battery life. Pencils are nice because they provide undo. If I just need to
find the answers for a one-off change or fix, I'll use plain white printer
paper (dated and labeled at the top for future archival or disposal). I'll
draw boxes/diagrams/mind-maps like crazy if I need them.

If its a major system that I'll be working with a long time, I go with
insanely cheap composition books of the same width and height (standardize!)
Seriously, don't spend more than a dollar for a notebook that has a good
chance you'll throw it away in a year. If you're going to use one for your own
journaling/designing and not mere notetaking, go ahead and splurge--spend $2.

Edit wrt Archival: Mostly, its being able to put the composition books away.
Label and date the front of them so you can flip through them. I use different
colors of covers so for any 4-5 of them I have "active" stand out and have
fewer problems grabbing "the wrong book" when I know which color is which
project. That's on the outside. On the inside, I reserve the first 5-6 pages
for a handwritten table-of-contents that I update approximately monthly. All I
do is dedicate one line per page in the book and summarize the contents of
that page. This makes is easier to find relevant content inside without having
to flip through 80 double-sided pages, I can skim 4-5 pages of topic lists.
When things get too old or irrelevant, dating them helps you figure out if you
need to throw the books away. (This is why you don't spend big money on these
books, e.g. I would feel really guilty about throwing away a nice Moleskine
book, but no qualms at all about tossing a $2 comp-book.)

~~~
nsomaru
Could you explain your archival system? If you're looking for something later
do you have an index or something to find the right page?

I'm also one of those people who is obsessed with speed and neatness (a
terrible combination) and if my notes are not beautiful I am loathe to keep
them. How can one manage this tradeoff?

~~~
sj4nz
(I added explanation of my indexing in previous comment.) Ditch cursive if
you're still writing in it. Pick up a $4 copy of "The Italic Way to Beautiful
Handwriting."

Remind yourself that the purpose of the notes is to off-load the work of long-
term memory from your brain until you have mastered your understanding of
whatever you're working on. That's all. Beautiful things are things you
publish and we don't publish books full of nothing but notes, no one else will
bother reading them unless you die famous. E.g.
<http://www.englishcompanion.com/pdfDocs/davincinotes.pdf> Most of us will not
die famous, so you shouldn't worry about your notes being beautiful. Davinci's
notes aren't especially "polished," that isn't why he made them.

Also, (from the pdf that reminded me), leave yourself some white space for
future communications with yourself as seen in
<http://en.wikipedia.org/wiki/Cornell_Notes>

~~~
Forrest7778
Organize your notes by page page number and paragraph - then you can label
revisions on a separate page pointing to the revised page. Using
sections/chapters helps with this as well.

------
gtani
Hmm, tough question to google but: I was going to blog about but: didn't get
around toit. Look at static code analysis and runtime tools (debuggers)
there's SO tags for that, python+code-analysis.

[http://stackoverflow.com/questions/3883484/using-python-
code...](http://stackoverflow.com/questions/3883484/using-python-code-
coverage-tool-for-understanding-and-pruning-back-source-code-o)

Python has a very rich toolset, including inspect module,

[http://stackoverflow.com/questions/1568544/given-a-python-
cl...](http://stackoverflow.com/questions/1568544/given-a-python-class-how-
can-i-inspect-and-find-the-place-in-my-code-where-it-i)

[http://code.activestate.com/recipes/213898-drawing-
inheritan...](http://code.activestate.com/recipes/213898-drawing-inheritance-
diagrams-with-dot/?in=user-1122360)

Also (this thread)[[http://stackoverflow.com/questions/334009/how-to-read-
source...](http://stackoverflow.com/questions/334009/how-to-read-source-code-
learn-how-to-use-large-system)] mentions ctags, doxygen, tools like that.
Reading test suites (and running code coverage) is where a lot of people start
with new to them codebases. And python specific emacs and vim plugins, and
python-specific IDE's, komodo and pycharm, at the tools they provide for
folding code, showing module dependencies/call graphs, stuff like that

\---------

My python's a little rusty, but could generate stacktraces, or use an IDE's
stepper/debugger to show where you are at some point in execution of django
code

\-----------

Finally [a book]([http://www.amazon.com/Code-Reading-Open-Source-
Perspective/d...](http://www.amazon.com/Code-Reading-Open-Source-
Perspective/dp/0201799405/))

