Reading Other People's Code (2012)

I'm quite stupid/forgetful, so when I write code I try to do it such that some unexpected 3rd party (i.e. me in about 3 weeks time) can read through and figure out what's going on. This generally means I include a sections both at the beginning of the code and in line which explain what I'm actually trying to achieve, broadly speaking. It's amazing how much easier it is to read complex technical code if you understand what the goal is.

Comments which describe the code are much less useful than a commentary regarding the code's objectives, in my opinion.

Maybe this says more about the quality of the code I have to work on or my own lack of ability.

Our legacy code often comes along with a large number of interfaces and dependency injection and it's difficult to find where the code actually 'does something'. So the only way I can understand what the code is doing is by stepping through it in a debugger.

If I just try to read it, I end up half a dozen classes away from the method I'm trying to understand in no time.

It says "Entire businesses have been built on the idea of sharing and writing code, but not reading." and links to Github, implying that Github is not built on the idea of reading code.

I think that's an unfair characterization. Certainly Github could do more to make code readable, but part of the reason that Github took off and largely replaced other alternatives was that it made it much easier to actually read the code instead of hiding it behind all the extraneous project administrivia. The project's code is still the first thing you encounter on a project's page, even emphasized above its README. Github's code browser is actually pretty excellent compared to a lot of the alternatives. There's fast navigation between files and decent syntax highlighting for a wide variety of languages.

I know that I at least spend a lot of time reading code on Github; probably more time than I spend doing anything else on Github. At any given time, I have a half dozen or so browser tabs open with Github code pages on 3rd party libraries that I'm using.

"Only thing you can be sure of is the source." not sure that's even true: http://cm.bell-labs.com/who/ken/trust.html

Unfortunately, it seems that the tool hasn't been worked on.

https://github.com/myusuf3/rainman

I am working on a tool that helps document how code has evolved that I believe is similar in spirit to this post:

http://www.storytellersoftware.com

I am actively working on it with students of mine.

Here are some thoughts on reading code:

We read code left to right, top to bottom, but how often is it written that way?

We need to be able to see the order that changes are made in order for us to understand them. Deltas in a version control system store the changes but we lose the order. The time in between commits in a version control system is way too long to understand how code has evolved. Because of this (and the loss of order) there is no good way to animate long term differences in a traditional version control system.

There is not a good place to document the reasons why changes are made. We are supposed to write the reasons why in the commit log but we all know we are terrible at that. How easy is it to remember the 50 changes to 20 files that we made since the last commit let alone describe them in a meaningful way? Very hard. This results in one sentence commit messages that are almost useless.

We could alternatively write reasons why changes are made in code comments. But, this doesn't make a lot of sense most of the time. Who wants to read a comment about how some code has changed if we can't see the old version of it anyway?

So, we make changes, and have good reasons why we make those changes, but we don't write the reasons down anywhere. Storyteller permits a new type of documentation to be created. It animates the changes to code and allows the developer to comment on the changes as they are being animated. Developers can tell stories about why groups of changes are made and distribute them to team members. The stories are searchable from the code.

We are also working on making it have traditional version control functionality to completely replace so-called modern version control (even the most modern vcs seem to be built with 1980's constraints- disk optimized, clunky command line interface, poor visualizations of changes, etc.)

It would be nice if there was some standard way to structure code so that it could be read through in order and mostly make sense. Maybe even a `how-to-read-this-code.readme' file which laid out an appropriate order to read things in, and making sure that the code is in an appropriate order.

I read this a year ago, I was really hoping for something to come of it.

Really cool idea.

I think reading code is a very good practice, and the more you read the easier "step 2" (the understanding bit anyways) becomes. That being said, I don't think reading through huge blocks of comments so that you can understand a function is useful. Forcing yourself to write self-explanatory code with a short docstring is a lot more useful than some hacky code with a huge comment explaining what it does.

I start by reading the tests.