What makes code "readable"?

[Terry Hancock]

[. ... regarding the use of short variable names ... ]
> 
> >>>>> "James" == James J Besemer <jb at cascade-sys.com> writes:
> James> However, for short names to be appropriate, the useage
> James> needs to be simple and very local in scope.  (Of course
> James> where to draw the line is a judgement call).

"Stephen J. Turnbull" <stephen at xemacs.org>:
> My experience in X?Emacs has been that the "many hands"
> eventually expand some scopes; not everybody is a good
> programmer, or they may have an "important" bug that needs
> "fixed right now".  So you should also consider how likely
> it is that somebody with a different design sense than you
> will work on the code later.

[Must confess I'm not sure what conclusion Stephen hoped
 we would draw from this -- it's clearly true, but I'm
 unsure what I should do about it.]

I frequently use shorter variable names in loops and other
local scopes as mentioned above -- sometimes I think this
can make things clearer or avoid errors. I recently had some
code that looked like this:

for view in views:
	...

This kind of bugs me because I always feel like I'm going
to leave out the 's' and get obnoxious bugs (more honestly,
I've gotten bitten by it enough to think that). So I
changed it to:

for vw in views:
	...

(Which I still say the same way, but this makes it harder
to confuse, I think).  I'm still waffling over it,
though -- which do you think is better?  Maybe I should
say 'viewtachi' and 'view', heh. ;-)  (Yes, I'm kidding).

I often have some confusion over whether to use plural
names -- it bothers me to name a list, say 'myfiles',
and then refer to an element as 'myfiles[2]' or something.
Of course, in Python you don't have to do indexing
like this as much (because of loop constructs like those
above), so maybe it's not so important (and maybe I
ought to return to the view/views instead of vw/views?).

Anyway, I don't think just having long or even long
pronounceable names is necessarily good -- it's got
to be meaningful to the programmer.  I'm not going to
be quick to forgive the Zope developer who came up
with 'bobobase_modification_time'. :-D I mean, sure,
after some time working with it and reading the history,
I've learned why it should be called that, but I'd still
have been happier with 'obj_mod_time' or something.

This is the other place where I use short variable
names -- when the short name *is* mnemonic.  I find that
i, j, k, m, n  are strongly mnemonic as counters, from
long use in various languages starting with Fortran,
and before that in mathematical notation. I therefore
try very hard not to use them for anything else.

Similarly, 'h_bar' may be much more mnemonic than
'reduced_plancks_constant', and the gravitational
constant had better be 'G', speed of light 'c', and
so on.  Obviously this stuff usually happens in the
number-crunching part of the code.  I do a lot less
of that nowadays, though.

(It should be appreciated that the above sentiment
is basically identical to the usage of equations
versus text in a technical paper. Clearly some things
are better explained in one mode or the other --
and some things ought to be both illustrated *and*
explained, which is where comments become mandatory).

Someone recently cursed "studly" caps -- I'm not exactly
sure what qualifies as that -- I find that GetSize or
similar capitalization can be useful. It's also good
to have different variable systems -- in C, I used to
use UPPERCASE for constants, MixedEmbeddedCaps for
global or module variables or other "relative constants"
and lower_case_w_underscores for normal local variables
and function names.

Now, with OOP in Python, I'm trying to standardize
on different schemes for methods and attributes and making
some effort to conform to Zope naming, since that's
what I'm working with mostly.  With such a zoo of
object types, I generally just try to make a distinction
between "verb-like" and "noun-like" objects.

All of this has reminded me more and more of the 
 "information architecture" approach described
in the O'Reilly book by the same name. That was talking
about publically accessable web resources and essentially
library science, but a lot of it would seem to apply
to good code design too. The author makes a big deal
about using consistent "labels" (which concept is pretty
much coincident with identifiers in programming languages).

It's a good read -- it made me realize what it was that
I was trying to do in designing programs and web pages
alike, but couldn't articulate well.  It's a lot
clearer objective to me now.  Of course, my current
project is pretty irrationally labeled -- fixing it
properly is going to be a major chore.  Fortunately,
I'm just compulsive enough to do it anyway. :-)

I also just recently came across the concept of object
"interfaces" in Python -- the Zope product developers'
tutorial now includes them. They basically strike me
as evil attempts to make Python resemble C++, but I'd
be interested to hear any arguments to the contrary.
What are they good for?  I'd need some good reason
to justify the accounting overhead of constantly checking
that my actual API matches the interface API.

These are not just academic questions, BTW -- I'm 
actually planning on how to rationalize my project,
which I hope will be in it's first release in a few
weeks.  Before I expose my code to world criticism,
it'd be sort of nice to work out at least the most
heinous violations of common sense and good design.
:-D

Cheers,
Terry

PS -- Apologies for the attribution mistakes earlier,
      I got confused, obviously.  And because I'm not
      going to post separately on it: touche to
      the "Perl-style" too-much-punctuation English.
      Funny. And true, of course. In all things,
      moderation! :-D

-- 
------------------------------------------------------
Terry Hancock
hancock at anansispaceworks.com       
Anansi Spaceworks                 
http://www.anansispaceworks.com 
------------------------------------------------------