I was reading through PEP 8, and I think there's a few things that could
be clarified or updated:
Exception Names
If a module defines a single exception raised for all sorts of
conditions, it is generally called "error" or "Error". It seems
that built-in (extension) modules use "error" (e.g. os.error),
while Python modules generally use "Error" (e.g. xdrlib.Error).
The trend seems to be toward CapWords exception names.
To my knowledge, except for some outlying cases like os.error or
socket.error (which are themselves old modules), CapWords are always
used. The less obvious question I'm wondering about is if exceptions
should have names that are relatively unique, or simply unique within
their namespace. Built-in exceptions use fairly long names, but then
they have no namespace. Looking at some newer stdlib modules: email and
optparse use longer-named exceptions; csv uses csv.Error. Should
"error" exceptions be discouraged? Would http.ServerError or
http.HTTPServerError be considered better?
Also, perhaps somewhere in the description of CapWords, how should they
deal with acronyms? It seems like the convention is, to give an
example, HTTPRedirect over HttpRedirect. I would appreciate an explicit
preferred style.
Global Variable Names
(Let's hope that these variables are meant for use inside one
module only.) The conventions are about the same as those for
functions. Modules that are designed for use via "from M import *"
should prefix their globals (and internal functions and classes)
with an underscore to prevent exporting them.
It seems like __all__ is a better technique than leading underscores.
Designing for inheritance
Always decide whether a class's methods and instance variables
should be public or non-public. In general, never make data
variables public unless you're implementing essentially a
record. It's almost always preferrable to give a functional
interface to your class instead (and some Python 2.2
developments will make this much nicer).
Yes, Python 2.2 developments have made this better. Use of property()
should be suggested.
Also decide whether your attributes should be private or not.
The difference between private and non-public is that the former
will never be useful for a derived class, while the latter might
be. Yes, you should design your classes with inheritence in
mind!
Private attributes should have two leading underscores, no
trailing underscores.
This conflicts with a previous suggestion "Generally, double leading
underscores should be used only to avoid name conflicts with attributes
in classes designed to be subclassed." Or perhaps "private attributes"
needs to be better explained.
Non-public attributes should have a single leading underscore,
no trailing underscores.
Public attributes should have no leading or trailing
underscores, unless they conflict with reserved words, in which
case, a single trailing underscore is preferrable to a leading
one, or a corrupted spelling, e.g. class_ rather than klass.
(This last point is a bit controversial; if you prefer klass
over class_ then just be consistent. :).
With class methods, this has become a more important. Can PEP 8 include
a preferred name for the class argument to classmethods? I personally
prefer cls, there are some who use klass, and I haven't see class_ used.
- Class-based exceptions are always preferred over string-based
exceptions. Modules or packages should define their own
domain-specific base exception class, which should be subclassed
from the built-in Exception class. Always include a class
docstring. E.g.:
class MessageError(Exception):
"""Base class for errors in the email package."""
I think the language against string-based exceptions can be stronger.
And this kind of implicitly indicates that longer names for exceptions
are better; how long? Should they generally end in "Error"?
--
Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org
_______________________________________________
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
