Por un lado, se nos anima a crear campos y no incrustar nuestras clases de python con funciones de acceso adicionales modeladas en otros idiomas.¿Se utilizan comúnmente las cadenas de caracteres de los atributos python?
Por otro lado, el PEP for 'attribute docstrings' fue rechazado.
En la tercera mano, epydoc y los respaldan. A riesgo de una pregunta no constructiva, ¿existe una práctica única, clara y común para documentar las variables en las clases?
Vuelvo a formular mi comentario como respuesta, ya que me lo pidieron.
Generalmente los atributos de la instancia (pública) se explican por sí solos y su uso por parte del usuario no requiere documentación. El nombre del atributo y el contexto es suficiente para dejar en claro cuál es el atributo y puede agregar un poco de documentación sobre cómo manejarlo en la documentación de la clase .
Puede terminar en algunas circunstancias en las que desee proporcionar al usuario el acceso de un atributo, pero el atributo no se explica por sí mismo y/o su manejo requiere atención (porque si no se maneja correctamente, podría " hacer estallar las cosas ").
Por ejemplo, es posible que desee que el usuario sepa que un atributo debe tener una "interfaz" específica para permitir su uso. O tiene que explicar una condición que debe cumplir el atributo.
En este caso, juntar la documentación con el documento de la clase no es una buena idea, ya que la documentación de la clase es cada vez más larga y explica muchos conocimientos realmente específicos.
La solución simple y, creo, más elegante es usar propiedades. Las propiedades le permiten agregar una cadena de documentación al atributo y para darle una forma de controlar realmente el acceso sobre ella, lo que permite hacer que la clase sea más robusta.
Si tiene que lidiar con una gran cantidad de atributos, puede ser problemático escribir decenas de propiedades, pero aún así puede agregarlas dinámicamente, por ejemplo, utilizando un decorador. Esto funciona bien, especialmente si solo desea agregar una cadena de documentos, utilizando siempre el mismo tipo de getter/setter.
Por ejemplo, usted podría escribir:
def set_properties(names_to_docs):
def decorator(cls):
for name, doc in names_to_docs.items():
prop = property((lambda self: getattr(self, '_{}'.format(name))),
(lambda self, val: setattr(self, '_{}'.format(name), val),
doc=doc)
setattr(cls, name, prop)
return cls
return decorator
Y utilizar de esta manera:
>>> @set_properties({'a': 'This is a', 'b': 'This is b'})
>>> class Test:
... def __init__(self):
... self._a = 1
... self._b = 2
...
>>> print(Test.a.__doc__)
This is a
>>> Test().a
1
En un comentario Lukas Graf señaló que es posible utilizar zope.interface para crear una clase que simplemente describe la clase concreta, que le da la oportunidad de agregar cadenas de documentos a los atributos. Esta probablemente sea otra opción. No tengo experiencia en el uso de Zope.interface, por lo que no puedo decir exactamente qué puede hacer y cómo, y cómo interactúa, eventualmente, con los programas de auto documentación.
esto es sólo mi humilde opinión, pero si los nombra de una manera auto documentada, especialmente con Python no necesita más documentación ... –
Tiendo a estar de acuerdo con @JoranBeasley, si mis funciones/clases son lo suficientemente grandes como para los atributos individuales necesitan documentación, algo huele divertido de todos modos. – Shep
Por lo general, simplemente los documenta en la documentación de la clase. Yo tampoco creo que realmente requieran algún documento especial. Si desea documentar que alguna variable requiere atención especial cuando se maneja (por ejemplo, debe ser de un tipo determinado o tener algún tipo de invariante, etc.), entonces * debe * crear una propiedad para ella. Esto le permite no solo agregar la documentación sino también implementar los controles que se requieren. – Bakuriu