The Psychotic State
			       Number 3
			   October 23, 1998

I try to do these about once a month.  October is not over yet, so I
haven't quite missed my deadline.


		     RANDOM MUSINGS ABOUT CODING

I suppose that most of you know that once upon a time I was an
academic.  In academia, there is a long period of indenture before one
actually gets to do anything, and the very first step of this is going
to graduate school.  Since there is not too much that graduate
students are qualified to do, most earn their living from the charity
of the university they attend.  In exchange - to balance the karma
somehow - that institution generally inflicts them on the unwitting
undergraduates as teaching assistants in introductory courses.

Thus it was with me.  My first job after graduating college was to
give sections in certain premed classes.  Though my responsibilities
did not generally include giving lectures, I did have an opportunity
to expound on the physical sciences before a small assemblage of
freshmen.  And it was in that context that I learned one of my lessons
in the nature of careful coding.  It was how to use a blackboard.

You see, when most people step up to a blackboard, they are seduced by
the power of holding the chalk in their hand and the sight of that
expanse of slate before them.  Their gut instinct is to think calmly
about their profound insight - grad students are full of profound
insights - walk to the center of the board, and write it right there.
And it's straight downhill from that point.

The problem is that this works only if the speaker has exactly one
insight to deliver.  The second profundity will have to go somewhere
else.  Below, maybe, but perhaps to the right or left.  And then the
third statement goes yet elsewhere, etc, etc, until the board is
a dog's dinner.

No, the right way to do it, as boring as it is, is to start writing at
the upper left corner of the board.  Most people have to strain even
to reach that point.  Write it there anyway.  Then, whatever needs to
be said next you place directly under that.  Then proceed down the
left of the blackboard.  I usually worked in a three column format,
but I used two if the equations were long.

It always struck me when I saw a much older professor who never quite
got it.  Really, as simple an idea as it was, there were those who
never really quite figured it out.  And on the other hand there were
lecturers who were just a joy to behold - far better than I ever was.
I swear that I sometimes marveled at how organized and methodical
these latter were, and their blackboard use usually matched the
clarity of their presentations.

All this was, naturally, before Mark Andreesen even started college;
it was even before gopher - centuries ago in web years.  But I was
musing on it recently when I was trying to figure out what it is that
makes a good coder.

Writing HTML, for example, is pretty much like writing on a
blackboard.  Frequently I run across code that's not indented, or
formatted in any way at all.  That's the simple seductive thing,
because the browser doesn't care.  Why not make it one long line?
Think, my friend!  How the hell is anyone other than the author
supposed to tell if it's right?  How is anyone going to tell how to
modify it?  It really doesn't matter _how_ it's indented; just
pick a way and do it.  It's not rocket science, but it made the
difference between the lectures you loved and those you cut.

Coding a program is like that in spades.  Unindented code is
unimpressive as well.  There are a billion filters out there to
prettify any language you can think of, and anyway the time it takes
to indent a program, even _manually_, is usually about 1% of the time
it takes to think about how to write it.

What do you think when you come across a program that's loaded with
commented out code from previous versions?  Of course a line or two
here or there is fine, but when there's tons of it in a file, it seems
that the author is really implying that s/he doesn't in fact believe
that the old code really needed to be removed.  Well then, why didn't
s/he just save the old version, in a directory called OLD?  When I'm
trying to figure out what a program is doing, do I really need to read
its entire revision history with all the bugs and wierdnesses
carefully preserved?  There was one time I hired a subcontractor who
_never_once_ deleted a line of code from the programs he was
modifying.  Eventually, it was left to me to comb through it all to
get rid of the garbage.


There's a whole pile of these sorts of things:

*) When you named the images were they consistent?  Or did you use
image_1.gif, image2.gif, and im3.GIF?

*) Are the directories of the site you just shipped loaded with files
called foo.html and xxx.old?

*) Does the name of the program you just modified actually reflect
what the program now does?

*) When you changed the contents of the .forward file, did you send a
test e-mail to see if it actually got to the new destination?

*) When you wrote that C program that used strcpy, were you sure that
the string being duplicated will fit into the buffer it's being copied
into?

It's all simple straightforward stuff that takes about no time flat to
learn, and just the slightest discipline to implement, and yet...

Edison was wrong.  It's not 1% inspiration and 99% perspiration.  It's
1% inspiration, 9% perspiration, and 90% reaching up to the top left
corner when you start.