Re: "static" declaration

[Dan Weinreb <address@hidden>]

Jeremy Hylton writes:
   
   I have been wondering, as this thread progresses, why do you want to
   have a notes that say what the instance variables of classes are?  

This is the way I go about understanding what the code is all about.
What is each class trying to abstract?  Where does each element of
state reside?

Suppose you were looking at a relational database and trying
to understand a bunch of code that does a bunch of queries
on it.  Surely the first thing you'd do is familiarize
yourself with the schema of the database.  You'd ask:

- what are all the tables?
- what are all the columns in each table and
    what does each of them mean?
- which foreign keys are referring to which primary keys?

Well, to me at least, it's much the same with programs written in
programming languages.  What are the data structures?  What are
the relationships between them?

In this case, a Proc_step represents a step of a process, and each
Proc_step says what tool did the step, what version of the tool, what
platform it was running on, what user was it done under the auspices
of, when was it done, and what's the English-text log entry (comment)?
Then there's a Sources object, which says: a process step was done
(reference to a Proc_step) object, and it used the following file
groups (list of names of file groups) and the following external data
sources (list of names of externals).  Each Sources has one Proc_step
associated with it (and, as it will turn out, vice versa). A
Constraint has an English-text "purpose"; every subclass of Constraint
expresses a particular constraint; one of them is the constraint that
that a date/time should be within a certain pair of bounds.  A File
Group has a name, a type (string, drawn by convention from a certain
set - no enums in Perl), an array of anonymous <filename, role name,
md5-checksum> objects of which there's one for each file in the group,
an array of Proc_step's, a Sources object (see above), and an array of
Constraints.

Once I know all that, I can start to understand how these objects
fit into the bigger picture.

Frankly, I was somewhat surprised by your question.  Doesn't everybody
approach new code this way?  I hadn't realized there was any other way
to go about it.
   
   It seems that knowing the complete set of instance variables is, by
   itself, rather uninteresting.  If I want to understand how a method
   works, the set of all instance variables isn't important.  Some
   instance variables won't be used in a method, and that fact isn't
   interesting.
   
Basically, I am learning the code by understanding it bottom-up.
Once I see what state is stored in each class of object, I can
better express in my head what the object really represents.

   Based on my very limited experience with Java, I expect that one
   advantage of knowing all the instance variables of a class is
   distinguishing between local variables and instance variables when
   you're reading code.  

That's definitely NOT what I'm talking about.

In fact, the Java conventions that we used at ODI/eXcelon for the BPM
project demanded that all instance variable names end with an
underscore, so that you can always tell which variables are instance
versus local.

		      In Python, instance variables are accessed as
   attributes of self, so this is always explicit.
   
That sounds like a good thing.  (Sorry, I have never had any exposure
to Python.)

   There are other useful things in Java declarations -- the type of the
   variable, its visibility, and, if needed, a comment explaining it's
   purpose.  In Python, I'd find some of this information in the class's
   constructor.  

Perl does not actually have a formal concept of "constructor".  It's
just a convention that you usually use "new".  In the code I've been
looking at, the construction is done by a method named "new" nine out
of ten times, but there have been one or two exceptions, and if I
had not read every line of code I would not have realized that I
was missing the constructor!

		 A typical Python class initializes instance variables in
   the constructor, which provides a helpful place to hang the comments.
   The comments are what I care about most.  They can document intended
   use, invariants, etc. that a type declaration doesn't capture.
   
The conventional "new" methods in Perl usually do this, mostly,
generally, but then sometimes some other method tacks on some more
instance variables later on, so, you just never know.  Never knowing
is not, in my opinion, a good thing.

   For example, in our own Python projects, when we create a lock, we
   document it's relationship to other locks and what instance variables
   its associated with.  The fact that lock1 must be acquired before
   lock2, or that lock2 must be held when writing var1, is more
   interesting than declaring that lock1, lock2, and var1 exist.
   
Indeed, and as I've said in earlier mail to this list, I wish that
languages had formal declarations that could say interesting things
like this.  Java's approach to this is kind of interesting and has to
do with the whole "Java memory model", which is one of the only
linguistic innovations in Java and, therefore, not surprisingly, one
that didn't work out perfectly and is currently being intensively
debugged and redesigned (William Pugh, I believe, is the Master of
this topic, if memory serves).

-- Dan