In the calculus of communication, writing coherent paragraphs that your fellow human beings can comprehend and understand is far more difficult than tapping out a few lines of software code that the interpreter or compiler won't barf on.
Definitive and most up to date? Without question.
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 practices 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 article, 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 substitute 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 critical a particular library or service becomes, the more important being able to see the details of its operation becomes.
I would very much like a “Read the source, Luke” t-shirt.
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 software. I still 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 activeX).
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 times. There is code out there that is worth reading. For me it is a way of learning, and I really enjoy it.
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 documentation. Fortunately for me, the source code is very well written; I learned more digging through the source than I ever would have found through Google.
Fun Fact: “Read the source, luke” was the standard answer on FreeBSD mailings lists some 10~15 years ago, whenever someone asked a question about how something worked. That is, whenever that question was asked on the developers mailing lists.
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.
but most importantly, reading high quality source code
can teach you a lot about programming and in a very short time
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 utilize in other projects. And then of course they license the content under creative 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 application.
“Nobody reads other people’s code for fun.” - Re:@Daniel Sobral
I used to browse SourceForge and Google code to learn new concepts of programming languages I wasn’t entirely familiar with…
Nobody reads other people’s code for fun? Hmmm…
I have fond memories of lounging on a sofa, reading printouts of Quake’s source. Those were very informative and entertaining sessions.
I prefer Drambuie or Grand Marnier, but sitting 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 productivity times. The code typically works, but all the inefficiencies, errors, junk, remain awaiting markup.
Documenting code is an art, but futile in most cases as the source will be a moving target. At best, it is an ought - but regression or unit test source are better 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 informative comments and on correct and informative documentation. Always demand the source code for your stack, but demand even more comments and documentation.
Seems to me there are three levels.
Obviously each involves more time 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 implementing 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. Sometimes reading source is a really good idea. Other times it means you are looking in the wrong place for your solution. 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 often leads me to finding a more targeted question to work with, and it always helps me understand the underlying processes at work better. I feel as though if more questions were framed with references to the source code, they may get more answers as they’ve shown a good-faith attempt and provide a good context to help others dig into the problem.
Great article Jeff… 
Currently I am working on same code base as it have very less documentation, but after reading this article I am inspired so much.
Keep posting such a nice and creative article… good luck.
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 software, it is a good idea to have a spec to design to, rather than just the code, because the spec may provide the intention of the code, whereas the code itself is providing the implementation, 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 platform below (to understand your application), doesn’t it come to understanding machine code and even electrical signals? I actually do support the idea that software developers (all sorts of programmers, actually) would be better off by basically reading the source instead of opening tens of support tickets when documentation isn’t helping – I just found that statement a bit too extreme.