That was definitely a wierd debate. I think we are being a bit too
defensive here. Tom's observations are not off the mark. Regarding
documentation, I find the tutorial to be "not bad" (though not enough to
forego buying Lutz's book), and the library and API references to be pretty
good (though I wish it had a keyword search since I always find myself
groking the index). I can't say the same for the PythonWin docs or the
pythoncom docs. The COM documentation is too informal, and doesn't match
the style of the other documentation. PythonWin's amount to three pages of
"preface" plus a sparse "quick reference appendix". The whole middle of the
book is missing, which is why I'm waiting for Mark Hammond's rumored "Python
for Win32" book with bated breath.
Now before anyone shoots me, I know these extensions are not part of "core
Python", so it's not "Python's fault" and certainly not Fred's fault if
their documentation is not up to the same standards. But maybe it is a
shortcoming of Python. I don't know if anyone has installed perl, but its
documentation is just immaculate, in man form and also in HTML. This
extends to the vast majority of the modules. To a lesser degree, Java
packages also have good, consistent documentation. This consistency in Java
and perl documentation is due, I think, to documentation facilities that are
included with the language distribution.
I guess no one saw the need for this in python because docstrings are built
in to the language (but you don't see the docstrings unless you're looking
at an interpreter window). Or natural selection meant that people who cared
about consistent documentation were selected out of the Python community (or
Python was selected out of their vernacular, depending how you look at it).
The same goes for things like that (elt,) single element tuple. That has
always bugged me. I believe that the only reason " '%s' % aString " works
is because otherwise that trailing comma would have shown its ugly face in
more places than it does. If the python syntax for creating a tuple didn't
look so much like the syntax for operator precedence, it would have been
better.
"(a+5,)*2" looks too much like "(a+5)*2"
or (worse?):
"(b+5.2)*3" vs. "(b+5,2)*3"
which is especially bad if you're French.
I've been thinking, maybe the Python community is just irreverant by nature,
owing to its namesake. This can be a good thing, or it can be a bad thing.
In terms of diplomacy with other camps, I think it is turning out to be a
bad thing. In terms of ignoring "old school" thinking and finding better
ways to do things, it's a good thing. (Until we fall into the trap of
introducing our own dogma. If we're going to be irreverant, we had better
be consistently irreverent, even toward ourselves!)
Bruce Dodson
defensive here. Tom's observations are not off the mark. Regarding
documentation, I find the tutorial to be "not bad" (though not enough to
forego buying Lutz's book), and the library and API references to be pretty
good (though I wish it had a keyword search since I always find myself
groking the index). I can't say the same for the PythonWin docs or the
pythoncom docs. The COM documentation is too informal, and doesn't match
the style of the other documentation. PythonWin's amount to three pages of
"preface" plus a sparse "quick reference appendix". The whole middle of the
book is missing, which is why I'm waiting for Mark Hammond's rumored "Python
for Win32" book with bated breath.
Now before anyone shoots me, I know these extensions are not part of "core
Python", so it's not "Python's fault" and certainly not Fred's fault if
their documentation is not up to the same standards. But maybe it is a
shortcoming of Python. I don't know if anyone has installed perl, but its
documentation is just immaculate, in man form and also in HTML. This
extends to the vast majority of the modules. To a lesser degree, Java
packages also have good, consistent documentation. This consistency in Java
and perl documentation is due, I think, to documentation facilities that are
included with the language distribution.
I guess no one saw the need for this in python because docstrings are built
in to the language (but you don't see the docstrings unless you're looking
at an interpreter window). Or natural selection meant that people who cared
about consistent documentation were selected out of the Python community (or
Python was selected out of their vernacular, depending how you look at it).
The same goes for things like that (elt,) single element tuple. That has
always bugged me. I believe that the only reason " '%s' % aString " works
is because otherwise that trailing comma would have shown its ugly face in
more places than it does. If the python syntax for creating a tuple didn't
look so much like the syntax for operator precedence, it would have been
better.
"(a+5,)*2" looks too much like "(a+5)*2"
or (worse?):
"(b+5.2)*3" vs. "(b+5,2)*3"
which is especially bad if you're French.
I've been thinking, maybe the Python community is just irreverant by nature,
owing to its namesake. This can be a good thing, or it can be a bad thing.
In terms of diplomacy with other camps, I think it is turning out to be a
bad thing. In terms of ignoring "old school" thinking and finding better
ways to do things, it's a good thing. (Until we fall into the trap of
introducing our own dogma. If we're going to be irreverant, we had better
be consistently irreverent, even toward ourselves!)
Bruce Dodson