

Reading Other People's Code (2012) - excid3
http://www.mahdiyusuf.com/post/32154944661/reading-other-peoples-code?utm=hackernews

======
alexholehouse
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.

~~~
ianlevesque
Yes, with code documentation write "why" not "how."

~~~
DigitalJack
I like to put it as "what for" not "what."

------
Silures
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.

~~~
mkramlich
Sounds like you encountered what I call an "Uh-O Architecture". It's basically
OO but overdone. Too many classes, too fine-grained, too abstract, too many
layers, too many designer patterns for the sake of design patterns, etc.

~~~
RogerL
I like that! I'm appropriating that term!

------
thraxil
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.

------
etherealG
"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](http://cm.bell-
labs.com/who/ken/trust.html)

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

[https://github.com/myusuf3/rainman](https://github.com/myusuf3/rainman)

~~~
avelis
Yeah it's just an empty shell for a project that never took off. Wishware at
this point.

------
markm208
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](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.)

------
thesteamboat
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.

~~~
akkartik
Ah, I've been trying to do just this.

Version 1: [http://github.com/akkartik/wart](http://github.com/akkartik/wart)

Version 2 (in progress):
[https://github.com/akkartik/wart/tree/master/literate](https://github.com/akkartik/wart/tree/master/literate)

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

Really cool idea.

------
ptzolov
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.

~~~
DigitalJack
I very much agree with this. Succinct comments have the advantage of being
easier to keep in sync with code changes.

------
jacobsenscott
I start by reading the tests.

~~~
avelis
To complement this I would suggest anyone to starting looking into BDD based
testing frameworks.

