[Python-Dev] Attribute docstrings [was: One-line abstractmethod function?]
Stephen J. Turnbull
stephen at xemacs.org
Sat Dec 7 02:05:07 CET 2013
Reply-To set to python-ideas at python.org.
Terry Reedy writes:
> For data attributes, which are usually mutable, it should be attached to
> the attribute *concept*, which is represented by the name, rather than
> the current but usually changeable value. Values are usually already
> documented either by a value representation or a docstring. This could
> be done with a string subclass that is used as needed.
> For methods, the value is nearly always constant. When multiple methods
> share the same function, they usually also share the same name, and
> represent the same concept.
Aside: Properties are which? Data, or method? It's also not clear to
me that "def first (self): return self.values" is unlikely to be
used for completely different purposes than getting the head of a
list. I conclude the considerations above are mostly red herrings.
The important thing, I suppose, is that the names of attributes
defined in a class are not mutable. This means that their docstrings
can be kept in a completely separate dict (or other string -> string
mapping), which could even be stored in a separate file. (Emacs Lisp
uses this to good effect. The DOC file for XEmacs is 1.6MB; for GNU
Emacs it's 2.4MB.) Of course it has its problems, but they're pretty
More information about the Python-Dev