

It's Harder to Read Code than to Write It - edw519
http://www.jakevoytko.com/blog/2007/12/22/reading-comprehension-will-make-you-a-better-programmer/

======
cduan
Great post, so true. One point I'd add, though: when you're writing code, make
it readable by commenting well! Sure it's obvious to you why you used a
ternary operator expression that uses a postfix-decrement operator and raises
an exception, but that's not clear to me. Until you tell me that you're
testing to see if an object reference count is zero, decrementing it if not,
and raising an error if so.

Good comments are tedious work and seem pointless at the time, but just wait
until you're reading your own code two weeks later, or even worse, someone
else's. The time you spent explaining yourself frequently makes up for the
time you'll waste later reimplementing what you did the last time around.

~~~
jamesbritt
> Until you tell me that you're testing to see if an object reference count is
> zero, decrementing it if not, and raising an error if so.

But that won't tell me _why_ your code is doing what it's doing

> Good comments are tedious work and seem pointless at the time,

Good comments should make you think about your code, not be some pain point
you are compelled to endure.

If you think it's tedious and pointless, there is a good chance the reader
(quite possibly yourself not to far in the future) will consider the comment
tedious and pointless as well.

~~~
cduan
> But that won't tell me why your code is doing what it's doing

Indeed, that's what the rest of the comment is for.

> Good comments should make you think about your code, not be some pain point
> you are compelled to endure.

Fair point. Yet the fact is that many people enjoy neither commenting nor
thinking about their own code, and that's not going to change. The question is
how to convince people to write good documentation in the face of intrinsic
motivations not to do so, and I think the best persuasion is a reminder of how
they will use that documentation later.

------
gruseom
It's harder to read _bad_ code than to write it.

~~~
parbo
No, _bad_ code is really easy to write.

~~~
gruseom
Am I missing something, or was one of us up too late? :)

~~~
brlewis
No, one of you didn't go to bed early enough. ;-)

