¿Cómo escribir docstrings significativos?

¿Qué, en tu opinión es una cadena documental significativa? ¿Qué esperas para ser descrito allí?

Por ejemplo, considere el __init__ esta clase de __init__ :

 def __init__(self, name, value, displayName=None, matchingRule="strict"): """ name - field name value - field value displayName - nice display name, if empty will be set to field name matchingRule - I have no idea what this does, set to strict by default """ 

¿Encuentras esto significativo? Publique sus ejemplos buenos / malos para que todos lo sepan (y una respuesta general para que pueda aceptarse).

Estoy de acuerdo con “Todo lo que no se puede decir de la firma del método”. También podría significar explicar qué devuelve un método / función.

Es posible que también desee utilizar Sphinx (y la syntax reStructuredText) para fines de documentación dentro de sus cadenas de documentos. De esa manera puede incluir esto en su documentación fácilmente. Para obtener un ejemplo, consulte, por ejemplo, repoze.bfg, que utiliza este extenso ( archivo de ejemplo , ejemplo de documentación ).

Otra cosa que uno puede poner en docstrings es también doctests . Esto podría tener sentido esp. para las cadenas de documentación de módulos o clases, ya que también puede mostrar de esa manera cómo usarlo y tenerlo a prueba al mismo tiempo.

De la PEP 8 :

Las convenciones para escribir cadenas de buena documentación (también conocidas como “cadenas de documentos”) se inmortalizan en PEP 257 .

  • Escribe cadenas de documentación para todos los módulos, funciones, clases y métodos públicos. Las cadenas de documentación no son necesarias para los métodos no públicos, pero debe tener un comentario que describa lo que hace el método. Este comentario debería aparecer después de la línea “def”.
  • PEP 257 describe buenas convenciones de docstring. Tenga en cuenta que lo más importante es que la “” “que termina una cadena de documentos multilínea debe estar sola en una línea, y preferiblemente precedida por una línea en blanco.
  • Para las cadenas de documentos de una línea, está bien mantener el “” “cierre en la misma línea.

¿Qué debería ir allí?

Todo lo que no se puede decir de la firma del método. En este caso, el único bit útil es: displayName: si está vacío, se configurará como nombre de campo.

Echa un vistazo a los docstrings de numpy para ver buenos ejemplos (p. Ej., http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

Las cadenas de documentación se dividen en varias secciones y se ven así:

 Compute the sum of the elements of a list. Parameters ---------- foo: sequence of ints The list of integers to sum up. Returns ------- res: int sum of elements of foo See also -------- cumsum: compute cumulative sum of elemenents 

Las cosas más sorprendentes que se me ocurren para incluir en una cadena de documentos son las cosas que no son obvias. Por lo general, esto incluye información de tipo o requisitos de capacidad, por ejemplo, “Requiere un objeto tipo archivo”. En algunos casos, esto será evidente a partir de la firma, no así en otros casos.

Otra cosa útil que puede poner en su documentación es un doctest .

Me gusta usar la documentación para describir con el mayor detalle posible lo que hace la función, especialmente el comportamiento en casos de esquina (también conocidos como casos de borde). Idealmente, un progtwigdor que use la función nunca debería tener que mirar el código fuente; en la práctica, eso significa que cada vez que otro progtwigdor tenga que mirar el código fuente para descubrir algunos detalles de cómo funciona la función, ese detalle probablemente debería haber sido mencionado en la documentación. Como dijo Freddy, cualquier cosa que no agregue ningún detalle a la firma del método probablemente no debería estar en una cadena de documentación.

El propósito general de agregar la cadena de documentos agregada al inicio de la función es describir la función, lo que hace, lo que devolvería y la descripción de los parámetros. Puede agregar detalles de implementación si es necesario. Incluso puede agregar detalles sobre el autor que escribió el código para el futuro desarrollador.