python development practices?

[brueckd at tbye.com]

On Wed, 31 Oct 2001, Peter Wang wrote:

> as an aside, and i don't mean to sound obnoxious, but why did guido
> not put in data hiding into python at an earlier stage?  my colleague
> whose background on generic programming comes entirely from the STL
> points this "wart" out as one of python's largest, and brings up the
> good point that data hiding was well known to the OOP world at the
> time of python's first incarnations.

"Well known" != "Always a Good Thing". Curly braces were also well-known
then too, and I'm very glad Guido chose against using them. :)

A good question to ask yourself (and your colleague) is why you want data
hiding. If it's to prevent against honest mistakes, great (notice that the
kind of data hiding that Python gives you does this). Be cautious,
however, about buying into notions about protecting your code against
rogue programmers, or programmers who try to subvert your code. If someone
wants to do that, they will, regardless of what fences you build into your
code.

Essentially it amounts to catering to immature programmers, which doesn't
make a lot of sense (you're teaching them it's okay to do whatever they
can *get away with*, instead of doing what they *should* do). As someone
else pointed out, if you are having to accomodate people who can't follow
simple directions, then you probably have bigger problems that need
dealing with. (there's actually a really interesting philisophical side to
all this: forcing people to do something makes them weaker, while teaching
them underlying principles and letting them experience for themselves the
plusses and minuses makes them stronger and self-reliant.  But hey, I'm
getting off topic).

A better approach is to cater to mature programmers and to use processes
that help other programmers mature too. A few places I've worked have used
something like the following (and these work well for non-Python code
too) and they really helped me:

If you're writing code that others will use:

- Provide some overview documentation, even if it's nothing more than 10
or 20 lines at the top of the module (or C++ header file or...). This can
be a high level description of how and why someone would use this library.

- As much as possible, avoid writing documentation that shows how to use
the APIs (except at a very high level). Instead, direct people to your
unittests of the module/library. Users of the code are confident that this
"API documentation" is accurate and up-to-date (since your unittests pass)
and that it reflects "legal" ways of using the code.

- As a user of the module, don't use APIs or access member variables not
tested in the unittests, or if you do, do so realizing that you're on your
own if things break.

We've used these guidelines and have had very few problems that you'd
consider related to "data-hiding". When breakage occurs, we go look at the
unittests (including the previous versions if needed) and compare it to
the code that broke. If breakage is due to the library maintainer changing
the documented use and behavior of the code, it's the maintainer's
responsibility to fix the problem, provide a good upgrade path, etc.

If the breakage is because someone was relying on a particular member
variable or non-public API, then it's up to that person to fix the problem
(where fix may include submitting to the maintainer a patch for a new API
and adding some new tests). There's really not much room there for
squabbles or other problems, and it takes either party about 1 mistake
before they learn to be more disciplined and follow the process.

Like I said, these worked for me and really helped me become more
disciplined.

-Dave