
Tips for Reading Code (2014) - dkarapetyan
http://wiki.c2.com/?TipsForReadingCode
======
spion
One of the tricks I like to use to get up to speed quickly is making a
hyperlinked dictionary / glossary (a wiki or a github page with anchor links
work nicely). The biggest roadblock to understanding the code you read is not
knowing the exact meaning of the terminology chosen by the original
developers. Building the dictionary helps internalise it quickly, leading to
much less confusion when reading.

Terms present in the UI (or API docs) of the segment you wish to understand
are a good starting point.

~~~
mysterydip
You might be interested in this single page app I made to handle similar use
cases of automatically hyperlinking documentation:
[https://github.com/elusivegames/termify](https://github.com/elusivegames/termify)
Sorry there's no live demo, but the readme should explain it easily enough.

~~~
techbio
Thanks for the link. I enjoyed the breakdown, and can see how it works, but
wow that code would be easier to read split up over three php files and a
template.

~~~
mysterydip
Definitely. The goal was something I could just drop in as one file to a
folder of docs, hence the ugliness :)

------
henrik_w
On the subject of reading code, I thought this was a good article (basically,
you can't read it like you read literature):

[http://www.gigamonkeys.com/code-reading/](http://www.gigamonkeys.com/code-
reading/)

~~~
morbidhawk
I agree with the opinion that reading code is not like reading literature but
I do find it useful to compare the 2 things. The book "The Psychology of
Computer Programming" talks about how most good novelists actually read lots
of novels while amateur novelists naively think they have enough inspiration
without reading ideas written by others. And the same thing happens with
programming, most really good programmers have read a lot of code in addition
to writing code. I have found this to be the case for myself, the more code I
read the more creative inspiration I have available when writing my own code.

------
hashin
I am being curious here. Do anyone really print out the code so that the
comprehension really increases? I can imagine all the benefits, but can
someone give any first hand experience were this has actually helped them?

Also, how better is it than the code map on Sublime Text or syntax colouring
we have anyway?

~~~
JoachimSchipper
I have done, for code that fits on 2-8 pages (basically a demonstration
program). I used vim's ":hardcopy", so the printed code was already syntax-
highlighted in the way I was used to.

This did let me work on the code when away from my workstation, but I didn't
otherwise find it very helpful. If you have lots of code, some form of code
navigation is very helpful.

~~~
tyingq
Vim's :TOhtml can be handy if you need to see syntax highlighed source on a
tablet or some other device that doesn't run vim.

------
SFJulie
I don't need to read the article to know in this case the best reading of
their code for rendering plain text in HTML should be to have absolutely no
code to read instead of any code they can have that might actually be
brilliant. Lol.

------
pasbesoin
So sad to see/experience c2 as a Javascript-dependent experience.

------
halayli
This article is basically saying use your brain.

------
minipci1321
Not sure in which context these tips were written. Having been through all of
this, and frequently comparing my code-reading abilities with those of my
junior colleagues (hey, I even managed to make it to a point where I
essentially make my living from reading other's code), maybe a few more-
realistic tips (and a shorter list):

1\. actually read the bloody code until you understand well what it does.
Don't stop before that, or it won't count.

2\. read as many different projects as you can -- different languages,
technologies, paradigms, coding styles.

3\. Don't spend time on code-comprehension tools, it won't work (speaking from
personal experience. The latest was with "Understand C++" from SciTools, a
great tool BTW). Master grep.

4\. Drawing flowcharts, running under debugger, etc -- all that would be great
but nobody allots time for that anymore (neither yourself nor your managers).

5\. Don't hope for usable doc for external libraries. Exceptions exist, but it
won't be a rule.

~~~
Lewton
1 always gets me.

My brain will tune out whatever piece of code I've already read once. So if I
initially skim some piece of code, figuring out what it -really- does is HARD.

Every subsequent look at that piece of code will be colored by my initial
(mis)understanding of how it works

~~~
thenobsta
Try reading it backwards. It forces your brain to look at the be text
differently.

This trick is also useful proofreading documents you've read many times
already.

------
microcolonel
The new c2 browsing experience makes me physically angry. My skin temperature
goes up, and my face makes an automatic scowl.

I don't know how they turned the most basic HTML page into something that
takes 30 seconds of spinner to load the same thing.

I counted 20 seconds to load
[http://wiki.c2.com/?SoftwareMasterpiece](http://wiki.c2.com/?SoftwareMasterpiece)

~~~
sgift
For a moment I thought this was another of the "meh, it uses JS, I want to
surf with my Lynx!!!!" rants but wow that page is really slow. I only counted
9 secs for the original page and 11 secs for your link, still ... for a bit of
text? Not even an image? What are they doing? setTimeout before they show the
HTML?

Edit: opening the same link again is instant. Weird.

~~~
jazoom
Ironically, this page looks like it doesn't even need JS. It's comical how
long it took to load.

~~~
dkarapetyan
Loads instantly for me. Might have something to do with your network or
service provider.

~~~
Groxx
Spinner loads instantly for me. Everything else takes ~10 seconds.

I'm on a 250 megabit connection. I haven't seen a page take this long to load
in _months_.

Once a particular page is visited, it does load quickly. But for new ones it's
always the same experience. Unless they're buckling under load of some kind
and this provides a fancy cache, it's pretty ridiculous.

\---

edit: decided to watch the network on a new page,
[http://wiki.c2.com/?LiterateProgramming](http://wiki.c2.com/?LiterateProgramming)
for instance. Most everything downloaded in 10s of milliseconds, but the
LiterateProgramming XHR request sat waiting for 6.5 seconds. Maybe they are
struggling for some reason?

~~~
dkarapetyan
You're right. Took a while for me on that one but second time around loaded
instantly.

------
bschwindHN
I'm impressed at how the author of this website managed to take plain text
content and literally make it slower to load than a 1080p 60FPS video. You
really have to _try_ to do something like that, bravo. I normally try to avoid
commenting on stuff like this, but that's pretty much all I can say
considering it took me actual _minutes_ to load (from Japan).

In lieu of the article's content, I'll spare readers the trouble and provide
something better (and faster to load!):

-Read lots of code

There you go, you're well on your way to becoming a code-reading master!

~~~
jasode
_> how the author of this website managed to take plain text content and
literally make it slower to load _

I didn't comprehensively debug the whole page but in a cursory 2 minute trace
in Chrome Dev Tools, I found javascript that makes an XHR request for a 265k
text file[1] with 36000 lines. The javascript code then parses the names
(which takes ~300ms) and then seemingly _does nothing with the information_.
It doesn't show up anywhere on any subsequent DOM rewrites. The actual
_visible_ content that people read is only 10k.

For mobile users, you punish them twice by (1) subtracting 265k from their
data plan and then (2) wasting battery power on cpu to parse it for no reason.
That one example of useless bloat is probably multiplied dozens of times
elsewhere in the lifecycle of the webpage.

[1] don't click on this if you're on mobile phone:
[http://wiki.c2.com/names.txt](http://wiki.c2.com/names.txt)

~~~
dom0
It doesn't seem to be the JS, though. The request that takes a whoppin' 33
seconds - server-side - for me is
[http://c2.com/wiki/remodel/pages/TipsForReadingCode](http://c2.com/wiki/remodel/pages/TipsForReadingCode)

------
falava
Wayback Machine archived copy:

[https://web.archive.org/web/20160709111543/http://c2.com/cgi...](https://web.archive.org/web/20160709111543/http://c2.com/cgi/wiki?TipsForReadingCode)

The Wiki was remodeled recently:

[http://c2.com/wiki/closed.html?WelcomeVisitors](http://c2.com/wiki/closed.html?WelcomeVisitors)

[https://news.ycombinator.com/item?id=12715560](https://news.ycombinator.com/item?id=12715560)

~~~
napsterbr
"Remodeled" is an understatement. It was destroyed. Luckily we have the
archive...

~~~
falava
I think he needs some time to improve it. More explanations here:

[https://github.com/WardCunningham/remodeling](https://github.com/WardCunningham/remodeling)

~~~
dom0
Given the state and performance of the site the tag line "The original wiki
rewritten as a _single page application_ " is practically satire: It's a SPA
now, _of course performance was degraded by a factor 100+_.

------
enibundo
I thought this was a fake article because of the spinning gif.

------
ensiferum
The page doesn't load.

