On 6/19/06, Ka-Ping Yee <[EMAIL PROTECTED]> wrote: > On 6/18/06, "Martin v. Löwis" <[EMAIL PROTECTED]> 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 appropriate. > 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/) _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
