[Python-Dev] uuid backward compatibility

Guido van Rossum guido at python.org
Mon Jun 19 21:54:15 CEST 2006

On 6/19/06, Ka-Ping Yee <python-dev at zesty.ca> wrote:
> On 6/18/06, "Martin v. Löwis" <martin at v.loewis.de> wrote:
> > As for the comment: It apparently *is* misleading, George mistakenly
> > took it as a requirement for future changes, rather than a factual
> > statement about the present (even though it uses the tense of simple
> > present). Anybody breaking 2.3 compatibility will have to remember
> > to remove the comment, which he likely won't.
> This sentiment is puzzling to me.  It seems you assume that we can trust
> future developers to change the code but we can't trust them to update
> the documentation.

It's sad but true that comments often are out of date for several
releases until someone notices them.

> So we can't have documentation even if it's factually
> true just because someone might forget to update it?  Why is the mere
> possibility of incorrect documentation in the future more significant
> than actual correct documentation in the present?  Couldn't the same
> argument be used to support removing all documentation from all code?

I think it has to be weighed in each case. In *this* particular case
the relevance of the comment seems quite minimal and removing it seems

> If you see a better way to word the comment to reduce the possibility
> of misunderstanding, that's cool with me.  I'd just like people who
> get their hands on the module to know that they can use it with 2.3.

Well even if the comment remains, they are going to have to try it
before they can trust the comment (see above). There is lots of code
in the stdlib that is compatible with Python 2.3 (or 1.5.2 for that
matter). How important is it to record that fact? I'd say not at all.

The Python standard library of a particular Python version shouldn't
be seen as an additional way to distribute code that's intended for
other versions. If you want to encourage people to use your module
with older versions, the right path is to have a distribution (can be
very light-weight) on your own website and add it to PyPI (Cheese
Shop). You can put the same version distributed with Python 2.5 there;
this isn't going to be something with maintenance and featuer
evolution, presumably, since it's only needed until they catch up with
2.5 or later.

If you still aren't convinced, how about a comment like this:

# At the time of writing this module was compatible with Python 2.3 and later.

--Guido van Rossum (home page: http://www.python.org/~guido/)

More information about the Python-Dev mailing list