Reading Other People's Code

Here's a few sources I really liked:<p>* Express - <a href="https://github.com/visionmedia/express" rel="nofollow">https://github.com/visionmedia/express</a> - I don't like TJ's coding style, and general trolling of CoffeeScript, but this is a really great, clean and tiny codebase. (As well as all the connect middlewares - <a href="https://github.com/senchalabs/connect" rel="nofollow">https://github.com/senchalabs/connect</a>)<p>* Async - <a href="https://github.com/caolan/async" rel="nofollow">https://github.com/caolan/async</a> - is very readable. Async is a great library for async ops handling in JS, and it's really neat seeing the implementation patterns.<p>* Ray - is a games DSL in Ruby - <a href="https://github.com/Mon-Ouie/ray" rel="nofollow">https://github.com/Mon-Ouie/ray</a> - I love it, and it's a great read especially if you are interested in DSLs as much as I do.<p>* Jekyll - <a href="https://github.com/mojombo/jekyll" rel="nofollow">https://github.com/mojombo/jekyll</a> - really helped me going forward with my ruby skills. It's nice, clean, commented, not too big, and useful.<p>* Redis - <a href="https://github.com/antirez/redis" rel="nofollow">https://github.com/antirez/redis</a> - lots of data structure implementations. Antirez just writes C so nicely. anet.c has networking, TCP bits, ae.c is an event loop. Lots of great code there.

"Programs must be written for people to read, and only incidentally for machines to execute." - SICP<p>If you believe this (and I do), then it follows that reading fluently is absolutely critical. One cannot judge writing without being a good reader.<p>You don't learn to write novels without reading a whole lot of them first. And someone who hates to read is never going to be a great writer.<p>I disagree that any special tool support is needed. If you depend on any open source library or platform at all, just don't stop bug hunting at the API boundary. Go down inside and see what's really going on.

This is a great idea. And I think that leads to a broader question I've had.<p>I completed a 10-week programming course (Hackbright) in SF this summer and am currently waiting for my visa to come through to come back to the Bay Area to start a job at a YC company.<p>There are lots of resources out there for picking up a language (or coding, to begin with), eg, codecademy, treehouse, udemy, even offline courses like Hackbright, DevBootCamp. Beyond that, what are some of the best ways to go from a programmer to a <i>good</i> programmer?<p>I find writing code a couple hours a day and working on my personal projects helpful, but only to a certain degree as I feel I am re-using a lot of my existing knowledge (or hitting some kind of roadblock).<p>Hence, reading more quality codes has been one of the priorities for me to keep up the learning. The major challenge though is to find good code to read. Perhaps a weekly curated "reading list" akin to StartupDigest but for coders, instead of startup related articles, they can be handpicked "codes of the week" on github / other sources? Or, do these things already exist out there?

I think that, except for the pure functional case, code can't be read without running it with a debugger. In imperative and oo there is too much "spooky action from a distance": with global variables, dependency injection or, god forbid, aspect oriented design, things seems to always happen elsewhere. Oh, and the solution to this problem is the same to the "cat -v considered harmful" problem: every program should do one thing and do it correctly, programs should be easy to compose, and interfaces between programs should be easy to inspect.<p>It is a vicious cycle: if a program source code is bloated, i won't be able to read it and understand it. If I don't understand it, I won't be able to use. Being not able to use it, I will reimplement its functionality in my program. Then, my program becomes bloated.

It's a really interesting idea. That said, talk is cheap, and the github repo seems to be nothing more than a 100b README at the moment. I'm looking forward to seeing a HN submission in a few months with a release.

There is a lot of fluff in this article, but the idea he leads up to and presents at the end is pretty fascinating.<p>I have tried to understand a large Linux kernel patch series by starting at the beginning and trying to go through the commits. I didn't make it far. Maybe I would have, if I had had a good tool to help (besides just git).

I disagree with a number of points in this article.<p>Businesses have been built on reading code. We (Architexa) are one such example, but there are lots more companies trying to help you browse/understand code. One of the older companies in this area is SciTools, which makes the 'Understand' product.<p>Beyond the above trivial point. The problem with books is that they are often designed to start from only one place (the first chapter). Blogs overcome this by letting you start reading at any post. If there really is a tool that is needed, it is a tool that helps you pick a way to start reading code. It is NOT to give you the one annointed way to read code (from where the writer started writing the code). You sometimes care about the code from the start to finish, or MUCH more likely you would want to read the code in a manner that aligns to your tasks - perhaps by seeing how the code responds to some event (by looking at the event hook), or seeing how the code uses a library or subsystem like the filesystem (by finding dependencies to the appropriate library).<p>Code reading/understanding is a <i>big</i> problem. And I am biased, but there is a lot of work that needs to be done here.<p>By the way, I would love your thoughts on what we are doing. Please check the video on our homepage (<a href="http://www.architexa.com/" rel="nofollow">http://www.architexa.com/</a>) and let me know either here or via e-mail what you think.

Every time I've set out to spend a good 20 minutes "code reading" random projects, I've learnt <i>something</i>. It might not be something big or even something positive, but I've always picked up something.. and strongly recommend it to anyone I tutor.

Recently I had to analyse the commit history of team members in a project and this tool: <a href="http://code.google.com/p/gource/" rel="nofollow">http://code.google.com/p/gource/</a> proved to be very effective.

I've come to realize that writing good code also involves good storytelling. There may be a thousand ways to get the job done, but the better coder will arrange and cluster things in ways that "flow" for the next human reader. Good coders also keep the next reader in mind, and don't use fancy-obscure ways to accomplish what could be done with more common techniques.

I like the idea of replaying commits. Never really thought about it because I tend to look at the current code without really bothering with the way it was developed or follow the commit history anyways if I'm developing myself.<p>I think the main benefits would actually be in the area of teaching. Just have people that learn to program watch replays of stuff in the language they want to learn and pick up on certain things via patter matching :)<p>At the very least even pretending to record your commits (rubber duck version) could probably improve your development process quite a bit. I think I'll actually pretend to record all my commits from here on out and give a running commentary to myself :)

Entering a new field is a fun experience. You start off by thinking "Wow, why has no-one done this before?" Sometimes, you've hit a new idea, and become a pioneer. Sometimes, you find a few similar attempts, but are still in unexplored territory. But what often happens is that you find there are entire conferences dedicated to the idea, and you simply hadn't heard of them. The world's a pretty big place, so this happens a lot.<p>Google for "program comprehension tool," and you'll see there's no shortage of tools to help people read code. Rather than create another one, someone should really just look at a bunch of those and create a "Top 10" list.

When reading code, I like to break projects down into chunks that I don't understand. Then I'll proceed to Google those bits, in an attempt to gain a broader understanding of what's going on (which in turn, increases my understanding of the language itself). Personally, I find this more fun than reading tutorials that never seem to get the point across. Personally, I love watching people code. Most just see the finished code, that is, the code the author committed. Few get to see the mistakes, typos, and general flow of the code in real-time. That's what I like to read/watch.

As the article somewhat alludes to, code isn't like a sequential book, but more like a conceptual system or a complex model. Rather than reading from top to bottom in a literal sense, the top you need to find to start with is the overview from 1000 feet (may the API or the design docs/specs), and you work your way down to the conceptual bottom or end of the story, which is way down in the implementation.<p>I'm not sure that the solution in the article achieves this in a coherent manor, and is only of relevance to one particular code repository (albeit a very popular one!), although it's never the less useful.<p>There is a class or two of tools that already exist and do help in this top to bottom process, doc generators and profilers (and sometimes debuggers). These work across all types of code repositories and all variations in quality of code. For instance, see the chap recently on HN who was trying to read and get to grips with a large code base [1] and my comments to him [2].<p>Granted these tools are versatile and go beyond just "reading" the code, perhaps there is some space for derived products which use these to create a "story" of the code from a top to bottom perspective.<p>[1] <a href="http://news.ycombinator.com/item?id=4557919" rel="nofollow">http://news.ycombinator.com/item?id=4557919</a> [2] <a href="http://news.ycombinator.com/item?id=4558801" rel="nofollow">http://news.ycombinator.com/item?id=4558801</a>

Great idea for a post and great idea for a project. I have thought about something similar. Encouraging people to read code, by making it easier to do, is a worthy objective.

When doing code reviews, I go through pull request commits in chronological order. It sometimes takes more time (eg. if the author didn't know exactly how to approach the problem from the start), but gives a much clearer picture of what was going on inside their mind when they wrote it.<p>That's one of the main reasons I dislike pull req squashing (or doing large compound "clean" commits in the first place). It destroys this information.

how much time <i>do</i> people spend reading other people's code?<p>am i unusual (lucky?) in having to do very little of this? usually i am developing new projects or maintaining things i wrote. even when extending existing work, reading the existing code is only a small part (largely at the start).

I don't think reading programming code compares to reading labview!