

On The Fear Of Reading Code - moconnor
http://coderoom.wordpress.com/2010/03/26/on-the-fear-of-reading-code/

======
mcantor
This reminds me of an excellent quote I heard a while ago:

"As a programmer, your job is not to write code. Your job is to solve
problems."

~~~
codexon
That sounds like the definition of any job.

As a janitor, your job is not to mop floors. Your job is to clean messy
problems.

~~~
mechanical_fish
True. And, yet, if the floors are spotless, but the janitor seems to spend 90%
of his day on the iPhone... How many managers are clueful enough to figure out
that _the janitor is accomplishing the task_ and leave him to do so in his own
way?

All kinds of people mistake work for a form of punishment: if you don't look
like you're toiling you must be doing something wrong. This is especially true
when evaluating someone _else's_ work.

~~~
herval
trivia: the portuguese form of work (trabalho) is a derivative of tripalium -
an ancient roman torturing tool.

So yeah, it kinda makes sense that some people take work as punishment... :-)

------
techdmn
To me, this is a Big Deal. I work with a coder with 20+ years of experience
who randomly re-implements parts of a massive legacy system to avoid reading
and understanding. Refactoring is unthinkable. Predictable results, now we
have two versions to maintain. :)

~~~
fierarul
What's surprising is that the legacy system still works after the
reimplementation. The guy might know what he's doing and this way he really
understands the domain now.

------
sophacles
I would like to add to the author's realization -- Frequently, if you look at
code you were "going to do better", and compare it to the original code,
you'll find you arrived at the same basic architecture, no actual improvements
or major differences.

------
astine
Sometimes, as an effort to read someone else's code, I'll actually refactor
and reformat it in an effort to understand it better.

~~~
wheaties
Refactoring is almost always good (almost the key word.) Reformatting, unless
the code follows no style what-so-ever, is bad.

~~~
araneae
Really? Reformatting will solve the "bracket should be on a new line" problem,
anyway.

~~~
Daniel_Newby
Promiscuous reformatting causes large, unreadable deltas for every commit to
the version control system.

~~~
Jach
So keep it isolated in a separate branch? I do agree style wars are pointless.

Personally, while I can and sometimes do have to use the style mentioned in
point #3 of the blog post, I curse under my breath every time. (It should be:
"\n} else {\n"! Not "\n}\nelse\n{\n"!) Saving myself that frustration can be
useful. But for a better example, I'll sometimes come across code indented
inconsistently with spaces and tabs, and need to reformat with :retab and ==
in vim. Separating complex code into chunks makes it easier to parse for me,
adding comments, etc. etc. etc. Remember, this is to understand the code, not
necessarily to make a bugfix. If I'm going to muck with someone else's code,
I'll usually follow their style even if it's not mine. But I might first solve
it in mine.

------
Chris_Newton
I had some similar lightbulb moments when I started investigating the
psychology of reading code. When you have some idea of how people with
different needs and different experience read and understand code, you start
to think about those factors when you write code yourself.

If anyone else is interested, my write-up is here:
<http://www.clarityincode.com/readability/> (I'm not sure about the etiquette
of linking to your own site from HN, so apologies if this is inappropriate.)

------
_delirium
I've found that with _good_ code, you actually have to read relatively little,
because comments explain what it does. You read a specific section if you want
to figure out the detail of what the comment says, or find it surprising
("really, it just does that in 5 lines?"). I try to do this with my own code,
because I don't even like reading _my own_ code.

Put differently, I 100% agree with Knuth's still-mostly-unheeded call for
literate programming, as the real solution to making code readable.

------
waratuman
Couldn't agree more. Lately I've read through some code in a language that I
never used before. But what I have learned from reading the code has had a
significant impact on the way in which I write my own code.

In my case I was reading some Clojure code. Functional programming was
something I had never really done much of. But after reading through code and
programming in it, I can say that it has significantly impacted the way I both
write and read Ruby code (not that I'll try to do functional in Ruby though
:).

------
jessejmc
Could anyone recommend particularly good Python code?

~~~
yan
django, twisted

~~~
thristian
Well, some parts of Twisted. All code added and edited these days has to
conform to style-guidelines and go through extensive code-review, so it winds
up pretty polished by the time it gets committed. On the other hand, Twisted
is a very old project and there's code in there that pre-dates the modern
quality requirements; such code is often... idiosyncratic, or at least
perplexing.

I'd recommend poking around well-tested things like twisted.internet.defer for
starters, then start to explore further afield. :)

------
afshin
"Code doesn’t rust and it doesn’t go off. Just read it, change it and use it."

I don't agree with this at all. In heterogeneous environments edge cases and
little used segments of code are often overlooked as other, more frequently
used, segments of a project are updated and their staleness is often only
discovered long after the actual "rusting" happened.

~~~
Chris_Newton
I quite like the way Lehman put it in his Law of Continuing Change: "A program
that is used and that as an implementation of its specification reflects some
other reality, undergoes continual change or becomes progressively less
useful."

Since reality typically changes, and software is typically a model of some
part of reality, standing still in absolute terms can be going backwards in
real terms.

------
pmccool
I agree that reading code is important. It follows from this that writing
readable code is important. It is telling, I think, that proofreading is nigh-
on ubiquitous with writing in prose, and nowhere near as popular with coding.

