Professional Documents
Culture Documents
Learn To Read The Source, Luke - Coding Horror
Learn To Read The Source, Luke - Coding Horror
Learn To Read The Source, Luke - Coding Horror
That's why, when it comes to code, all the documentaƟon probably sucks. And because wriƟng for people is
way harder than wriƟng for machines, the documentaƟon will conƟnue to suck for the forseeable future.
There's very liƩle you can do about it.
The transformaƟve power of "source always included" in JavaScript is a major reason why I coined – and
conƟnue to believe in – Atwood's Law. Even if "view source" isn't built in (but it totally should be), you should
demand access to the underlying source code for your stack. No maƩer what the documentaƟon says, the
source code is the ulƟmate truth, the best and most definiƟve and up‐to‐date documentaƟon you're likely to
find. This will be true forever, so the sooner you come to terms with this, the beƩer off you'll be as a soŌware
developer.
I had a whole entry I was going to write about this, and then I discovered Brandon Bloom's brilliant post on
the topic at Hacker News. Read closely, because he explains the virtue of reading source, and in what context
you need to read the source, far beƩer than I could:
I started working with MicrosoŌ plaƞorms professionally at age 15 or so. I worked for MicrosoŌ
as a soŌware developer doing integraƟon work on Visual Studio. More than ten years aŌer I first
wrote a line of Visual Basic, I wish I could never link against a closed library ever again.
Using soŌware is different than building soŌware. When you're using most soŌware for its
primary funcƟon, it's a well worn path. Others have encountered the problems and enough
people have spoken up to prompt the core contributors to correct the issue. But when you're
building soŌware, you're doing something new. And there are so many ways to do it, you'll
1 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
building soŌware, you're doing something new. And there are so many ways to do it, you'll
encounter unused bits, rusty corners, and unfinished experimental code paths. You'll encounter
edge cases that have been known to be broken, but were worked around.
SomeƟmes, the documentaƟon isn't complete. SomeƟmes, it's wrong. The source code never
lies. For an experienced developer, reading the source can oŌen be faster… especially if you're
already familiar with the package's architecture. I'm in a medium‐sized co‐working space with
several startups. A lot of the other CTOs and engineers come to our team for guidance and
advice on occasion. When people report a problem with their stack, the first quesƟon I ask
them is: "Well, did you read the source code?"
I encourage developers to git clone anything and everything they depend on. IniƟally, they are
all afraid. "That project is too big, I'll never find it!" or "I'm not smart enough to understand it"
or "That code is so ugly! I can't stand to look at it". But you don't have to search the whole
thing, you just need to follow the trail. And if you can't understand the plaƞorm below you, how
can you understand your own soŌware? And most of the Ɵme, what inexperienced developers
consider beauƟful is superficial, and what they consider ugly, is baƩle‐hardened
producƟon‐ready code from master hackers. Now, a year or two later, I've had a couple of
developers come up to me and thank me for forcing them to sink or swim in other people's code
bases. They are beƩer at their craŌ and they wonder how they ever got anything done without
the source code in the past.
When you run a business, if your soŌware has a bug, your customers don't care if it is your fault
or Linus' or some random Rails developer's. They care that your soŌware is bugged. Everyone's
soŌware becomes my soŌware because all of their bugs are my bugs. When something goes
wrong, you need to seek out what is broken, and you need to fix it. You fix it at the right spot in
the stack to minimize risks, maintenance costs, and turnaround Ɵme. SomeƟmes, a quick
workaround is best. Other Ɵmes, you'll need to recompile your compiler. OŌen, you can ask
someone else to fix it upstream, but just as oŌen, you'll need to fix it yourself.
Closed‐soŌware shops have two choices: beg for generosity, or work around it.
Open source shops with weaker developers tend to act the same as closed‐soŌware
shops.
Older shops tend to slowly build the muscles required to maintain their own forks and
patches and whatnot.
True hackers have come to terms with a simple fact: If it runs on my machine, it's my soŌware.
I'm responsible for it. I must understand it. Building from source is the rule and not an excepƟon.
I must control my environment and I must control my dependencies.
Nobody reads other people's code for fun. Hell, I don't even like reading my own code. The idea that you'd
seƩle down in a deep leather chair with your smoking jacket and a sniŌer of brandy for a fine evening of
reading through someone else's code is absurd.
But we need access to the source code. We must read other people's code because we have to understand it
to get things done. So don't be afraid to read the source, Luke – and follow it wherever it takes you, no maƩer
how scary looking that code is.
[adverƟsement] Stack Overflow Careers matches the best developers (you!) with the best employers. You
can search our job lisƟngs or create a profile and even let employers find you.
2 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
Related posts:
53 Comments
Best? That's arguable, and depends on the code base. Learning a language from the source (say Python or
SQL) is a really bad idea. Best pracƟces and KISS for the code is not something you'll learn from that.
@sqlrob: The answer to your point is in the middle of the arƟcle, and nowhere near as prominent as it
should be. "you should demand access to the underlying source code for your stack" Emphasis mine.
Certainly for learning languages there is no subsƟtute for expert guidance, whether it's through books,
classes, etc.
But for any libraries that your code depends on, you will at some point wish you had the source code, even
if it's a mess. The more criƟcal a parƟcular library or service becomes, the more important being able to see
the details of its operaƟon becomes.
Granted I've only been in this industry for 9 years, but "maintain their own forks and patches" seems like
advice that should only be used as a last resort.
When you do this you really hurt your upgrade path, and it is easy to get stuck with certain versions of
soŌware. I sƟll cringe when I think of the shops have to use windows xp and IE 6 because of these kinds of
dependencies (of course this is probably more due to acƟveX).
I read code for fun. Well, for enjoyment. And, yes, real code too, not just the clever algorithms and snippets
3 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
I read code for fun. Well, for enjoyment. And, yes, real code too, not just the clever algorithms and snippets
that abound on the web.
"fine evening reading through some else's code is absurd". Really? I've done that a lot of Ɵmes. There is
code out there that is worth reading. For me it is a way of learning, and I really enjoy it.
This is one that drives me nuts on iOS. I'm forced to class dump and decompile to understand the issue or
the undocumented behavior.
In Android, it's easier because the source. Unfortunately it lags really far back from the binary release
before it becomes open. It's frustraƟng.
On the .NET stack, MicrosoŌ listened and they include the source stubs in a download that Visual Studio
will download. If you are stepping through into a system library, it shows you the actual source code (to
level but it's beƩer than nothing).
Absolutely true. I've been using SlickGrid for data display clientside for a while now. It's an amazingly
capable library, but it has nearly no documentaƟon. Fortunately for me, the source code is very well
wriƩen; I learned more digging through the source than I ever would have found through Google.
Reading source code is hard. This is mostly because the order that we read it is oŌen not the order that we
write it. The order really maƩers. In addiƟon, the context and the reasons 'why' the code looks like it does is
usually not present in the code.
Version control systems do not record this order or context. They take snapshots. A lot of interesƟng things
happen in between the snapshots. This means a good deal of informaƟon is leŌ on the cuƫng room floor.
Further, there is a narraƟve in our heads while we write code. This narraƟve has all the context and reasons
why we are doing things in it. We almost never write this narraƟve down anywhere. We remember it for a
liƩle while but eventually it escapes into the ether.
I am working on a tool that records almost all of the data associated with a programming session and allows
a developer to tell a 'story' about what they did and why. It has version control funcƟonality (branching and
merging) but offers a more useful documentaƟon tool than simple commit messages.
Fun Fact: "Read the source, luke" was the standard answer on FreeBSD mailings lists some 10~15 years ago,
whenever someone asked a quesƟon about how something worked. That is, whenever that quesƟon was
asked on the developers mailing lists.
You could've goƩen your point across in 5‐10 lines, everything aŌer the first 2‐3 paragraphs is just you
repeaƟng yourself. Also, why don't you follow your own advice and release the source code for
Stackoverflow?
And its funny that you invented your own rule and call it the Atwood rule. Its also a bit sad.
you also want want to read source code to learn from it even if not part of your stack
it can help you to learn a new language, understand differences between languages, etc.
Re open sourcing Stack Overflow: Jeff actually pushed for this in the early days of Stack Overflow, but he got
push back on it and they never did it. And to be fair, they have open sourced several pieces of it that make
sense to uƟlize in other projects. And then of course they license the content under creaƟve commons,
which I find quite admirable.
Also, I don't think open sourcing Stack Overflow really helps much as far as the point he is making... Stack
Overflow shouldn't really be an element in your stack, unless you are developing a stack app. Thus almost
nobody really needs the source to overcome programming obstacles for their applicaƟon.
5 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
I used to browse SourceForge and Google code to learn new concepts of programming languages I wasn't
enƟrely familiar with...
I prefer Drambuie or Grand Marnier, but siƫng back with a hardcopy of my latest source and a pen (red,
preferred, I have a Lamy fountain pen with dark red ink in a converter) is one of my highest producƟvity
Ɵmes. The code typically works, but all the inefficiencies, errors, junk, remain awaiƟng markup.
DocumenƟng code is an art, but fuƟle in most cases as the source will be a moving target. At best, it is an
ought ‐ but regression or unit test source are beƩer enforcerers.
The whole "read the source code, luke" is fine. News at eleven. Same with the whole "comments probably
suck".
But the emphasis should always be on correct and informaƟve comments and on correct and informaƟve
documentaƟon. Always demand the source code for your stack, but demand even more comments and
documentaƟon.
i mean...
any rookie can use SHIFT‐F2 all the Ɵme, but there is a very hidden pleasure on pressing PG‐DN unƟl you
RECOGNIZE the part of code you're looking for
could be just for hackers, indeed, but doing it in double 20+ inches' this day monitors... feels reaaaaaaly
6 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
could be just for hackers, indeed, but doing it in double 20+ inches' this day monitors... feels reaaaaaaly
cooool :‐)
if almost everybody learn to use tab for "horizontal" indent... why not encourage them to do the same with
"verƟcal" indentaƟon, separaƟng pieces of code in meaningful and recognizable (i swear) chunks?
this relies in a past century theory about using both your brain hemispheres AT ONCE, the logical one and
the "visual/creaƟve" one
be an intellectual‐arƟst!
br
1) read docs.
2) read source.
3) write it yourself.
Obviously each involves more Ɵme that could be spent doing other things; the ideal if you are using a
common tool is to have good docs. But it's facile to suggest that one should just read the source when
encountering a problem implemenƟng a program, plugin, module, what have you. Am I going to read
ffmpeg source when it borks in ./configure? Probably not. Will I use an un‐minified jquery plugin to trace
the source of an error? Almost always. SomeƟmes reading source is a really good idea. Other Ɵmes it means
you are looking in the wrong place for your soluƟon. Ask the bear. If the bear won't answer, then read the
source.
I've found that I can't always find the answer from diving into the source code, but it oŌen leads me to
finding a more targeted quesƟon to work with, and it always helps me understand the underlying processes
at work beƩer. I feel as though if more quesƟons were framed with references to the source code, they may
get more answers as they've shown a good‐faith aƩempt and provide a good context to help others dig into
the problem.
Currently I am working on same code base as it have very less documentaƟon, but aŌer reading this arƟcle I
am inspired so much.
I think that reading the source is perhaps the quickest way to see what is going on so you can get something
done. But when it comes to designing soŌware, it is a good idea to have a spec to design to, rather than just
the code, because the spec may provide the intenƟon of the code, whereas the code itself is providing the
implementaƟon, which is more likely to change (one would hope, anyway).
If there is a difference, it's best to try to submit a bug report or tech support request of some sort, if this is
possible, to clarify things.
But, in the end, the code needs to work, so it's best to read both and try to figure out which side is right.
If you always need to understand the plaƞorm below (to understand your applicaƟon), doesn't it come to
understanding machine code and even electrical signals? I actually do support the idea that soŌware
developers (all sorts of programmers, actually) would be beƩer off by basically reading the source instead
of opening tens of support Ɵckets when documentaƟon isn't helping ‐‐ I just found that statement a bit too
extreme.
The source may well be the most up to date and the 'truth', but it is by no means correct.
Although not a big fan of documenƟng the obvious I think that specificaƟons should be mandatory, this
way you know what the expectaƟons were of the applicaƟon, and the source code can not, and should not
be the definiƟve source of such informaƟon. However I do agree that, parƟcularly when bug fixing, you
should be drilling down straight into the source and not much else if you want a speedy resoluƟon, and all
developers should be capable of doing this.
I think documentaƟon pays off when you are providing reusable frameworks and other soŌware, and even
then it should be basic guidelines etc.
Damnit Jeff, I just spent the last 20 minutes looking for an easter egg in your html source code.
I agree with K Lawrence. The source code says what the applicaƟon/library/widget does, not what is
supposed to do. Some kind of documentaƟon is needed.
Whenever I use a method or library created by someone else, inside my company or outside I don't want to
look into the source code unless unavoidable. I just want to know how to call it, or what it does, or what is
the flow.
8 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
the flow.
For self‐improving reasons I will want to read the code. But for the compleƟon of the work, shouldn't be
necessary.
While there are some correct observaƟons regarding the availability of source code, i'd like to focus at the
start of the arƟcle, where i strongly disagree.
In short, it says "DocumentaƟon always suck in many ways and it will always do. Don't even lose your Ɵme
with it, just read the code". And since it is useless this also implies that you should not bother to write it.
That's absolutely WRONG in my opinion.
A complete documentaƟon is important, it's not just a reference to what a funcƟon does. It also tells you
what classes are available and when you should use them. If it is properly wriƩen it's much beƩer than
trying to read the source cose which may use a syntax you're not used to and various implementaƟon
details that you can't know. Try to read subversion source code.
Just yesterday i was reading a discussion on git where the developer used Javascript implicit statement
separator (which means you don't put the semicolon) and expression short‐circuit instead of a normal if
statement. The first of these even breaks some javascript minimizers. Am i supposed to read the code,
understand these paƩerns, figure out what they're doing and what that var is used to instead of just
reading a good documentaƟon? That's crazy.
Sigh. So, another blow for cowboy/hero coding is struck. "DocumentaƟon is haaard!" So... just give up?
No. DocumentaƟon is essenƟal. Sorry. If your code is clear, concise, self‐documenƟng, that's great, I totally
support that (and, even if it's not, I sƟll want your source code), but I want to point out that that sort of
lovely self‐documenƟng code comes about because the coder thought of the person to come aŌer, so that
coder actually wrote DOCUMENTATION (it just happens to be executable).
Coding in a furball, piling up hacks, refusing to document and then handing the whole steaming mess to
somebody who asks quesƟons is chickenshit.
I have so had it with people using agile and "use the source, Luke" as an excuse for bad behavior. Yes, I
know that if developers had the kind of social skills required for wriƟng good documentaƟon (as in:
understanding the audience enough to know what quesƟons they'll have, given that they're not an exact
clone of you, the developer) they'd be something besides coders, but the answer is not "give up and tell
'em to read the code."
9 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
This is a contenƟous view because everyone has their own experience of code and documentaƟon.
A system with lots of external interfaces and dependencies probably needs some.
Where I think all experienced developers agree is that code must be wriƩen with support and maintenance
in mind.
hƩp://cvmountain.com/2011/09/whats‐wrong‐with‐this‐code‐really/
Whether or not the system also needs documentaƟon depends on the system and the context in which it
will be maintained over its life.
This is one of the reasons I don't like abstracƟon layers. You can't predict exactly what they're going to do,
and you [mostly] can't read the source code to find out.
I think I appreciate the point you're trying to make and I agree that people would do well to learn to read
the source.
However, I disagree with your statement "No maƩer what the documentaƟon says, the source code is the
ulƟmate truth, the best and most definiƟve and up‐to‐date documentaƟon you're likely to find."
(Good) documentaƟon is a descripƟon of what the soŌware designer/programmer wanted to write, the
code is what they ended up wriƟng. If all goes well, these two are the same. But if mistakes were made,
odds are only one of the two is wrong and the other offers a clue what was really intended.
Note that this also implies that, someƟmes, the code can help fix broken documentaƟon.
10 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
1) Wrong code revision: The source you're looking at is from version 3.00, but you're actually running on
version 3.14.159.This mostly happens when you used pre‐compiled binaries instead of building the
applicaƟon/library yourself. Or because you Googled for the relevant source keyword instead of searching
through your own local source files.
2) Wrong file(s): You *think* that you're looking at the right code, but it turns out that it's an unused copy
or variant that isn't actually what's compiled into the library you're using. This oŌen happens when you're
dealing with code that's meant to be compiled for mulƟple targets, eg. Linux kernels and drivers. Other
Ɵmes it happens because a file was moved or replaced, and the old version was leŌ lingering in the
repository.
hƩp://blog.ezyang.com/2012/04/use‐the‐source‐dont‐read‐it/
When I read this a couple of hours ago I agreed with it 100%, then I read about the publicaƟon of the
original Prince Of Persia source code on GitHub and, although the sniŌer of Brandy was a tumbler of
Bechrovka, sat down for a fine evening of reading through someone else's code!
Link: hƩps://github.com/jmechner/Prince‐of‐Persia‐Apple‐II
Reading the source code is not the soluƟon to bad documentaƟon, contribuƟng to fixing the
documentaƟon is the proper thing to do.
Relying on source code and bypassing official documentaƟon is asking for trouble. The source code may
reveal undocumented features that are not guaranteed to be available in future versions of frameworks.
Precisely ‐ and that's more of a problem if the developer is not a naƟve English speaking person. The
comments he/she may write not bring out the actual meaning. On the other hand, the code is always there.
In a good IDE any badly formaƩed code can be looked in a a lot more meaningful way.
And most of the Ɵme, what inexperienced developers consider beauƟful is superficial, and what they
consider ugly, is baƩle‐hardened producƟon‐ready code from master hackers.
Ole Eichhorn: "This is one of the reasons I don't like abstracƟon layers. You can't predict exactly what
they're going to do, and you [mostly] can't read the source code to find out."
I have the EXACT SAME issue with projects that use inversion‐of‐control. Makes it IMPOSSIBLE to figure out
the flow of the code unless you're using a debugger!
I also hate the current "minificaƟon" trend in web dev, because it creates source that's completely
indecipherable. Yes, I can go grab the un‐minified version from the original site, but what if a specific
website has made their own changes?
Code should not need documentaƟon external to the code itself to be understandable. Fin.
I only parƟally agree with your statement. Reading the source is important, but reading the source is
Ɵme‐consuming.
When you have Ɵme contstraints, having code (especially third party libraries) where documentaƟon and
code are coherent in behaviour, and especially where all available funcƟons (i.e. public API) are well
documented, that's a real plus and speaks for the quality of the "supplier".
When you have API and code that don't match, a load of undocumented features and you go on by (even
obvious) trial and error, that's not good because you always have in the back of your mind the idea that the
block/component/library you're using is not producƟon ready and can become a thorn in your side.
Then, of course, reading a WELL WRITTEN and WELL DOCUMENTED source is a way to improve oneself, as
much as reading a book in a foreign language you want to master.
I agree with the final statement from Zmaster: "Good documentaƟon is a must, don't oversee it."
@Jeff
Didn't you develop StackOverflow on the MicrosoŌ stack? I remember a post from way back jusƟfying the
decision.
12 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
How are you holding these "Use the source Luke" and using MicrosoŌ stack ideas simultaneously?
@Dehaul
With tools like reflector, you can look into the .NET framework fairly easily.
@Jeff
Your related posts link doesn't work with middle click. IT simply opens the page in the same tab instead of a
new one. Do me a favor, read the source and fix it. It's annoying. I'd do it myself, but you'd be angry :)
I had a friend who always said: "Moses brought the source code down from the mountain, not the
documentaƟon."
@Jeff ‐ You're channelling Adele Goldberg ‐ one argument she's well known for is her opposiƟon to teaching
people to write code before they learned to read it ‐ her observaƟon was that nobody would ever teach
someone to write prose without having them read some first ‐ and that in turn became a core philosphy of
SmallTalk ‐ all the code for the enƟre system was visible, and if you wanted examples or ideas, they were
there for the taking, as well as the ability to see exactly how things were done
This blog is wonderful, thank you propose. Glad to see new projects! I wish you much success .
Voyance
Shameless plug but with the honest intent to help out those who find code reading difficult.
We are starƟng a free code reading study group. IniƟally it will be ruby, but we have plans for js.
We're just geƫng started and currently discussing our first project to explore. So far 150 people have signed
up so it should make for some good discussion and study.
hƩps://ƟnyleƩer.com/codereading
This is non commercial and in totally in the spirit of helping out each other.
13 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
This is non commercial and in totally in the spirit of helping out each other.
I forgot to say thank you for an excellent blog post. It's partly what spurred me to start the study group.
@Jaap Van der Velde: "(Good) documentaƟon is a descripƟon of what the soŌware designer/programmer
wanted to write"
Not exactly true. DocumentaƟon is a descripƟon of what the developer wanted to write *when they wrote
the documentaƟon*. However, the probability that the documentaƟon will skew from revised intenƟons
approaches 1 as the code becomes more mature. The code is the only truth about what a given rouƟne
actually does as opposed to what the documentaƟon claims it does. It is the (current) users that dictate
what it ought to be doing.
TBH, what is being discussed here are black boxes. If you drop a component into your soluƟon and it works
as expected, then the source of the component isn't necessary. The problem comes when the black box
doesn't do what you expect and you have to figure out why. If the documentaƟon helps to get over your
problem, then great but at the end of the day, what really will help get past the problem is the source of the
black box. That will truly tell you how the component is actually working.
Well said, but considering that your main plaƞorm is Windows it's also ironic.
Using applicaƟon is different than developing applicaƟon. When you're using most applicaƟon for its main
operate, it's a well used direcƟon. Others have experienced the issues and enough individuals have verbal
up to immediate the main members to appropriate the problem. But when you're developing applicaƟon,
you're doing something new.
Good read. Also another point is that all the really good product companies rely on you reading code for
you training! Which is really awesome. AŌerall well wriƩen code is the best form of documentaƟon there is
to a developer!
14 de 15 22/06/2012 08:59
Coding Horror: Learn to Read the Source, Luke http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-lu...
www.seczine.com
15 de 15 22/06/2012 08:59