Buenas Practicas De Programacion Docstrings
Que lleva un doctring?
Un doctring es la cadena de documentación que tiene cada módulo, clase y función
en python y que podemos ver con el comando doc o el comando help. EStas
cadenas fueron hechas por los programadores de los módulos para que de un
vistazo rápido otros programadores puedan comprender y utilizar su código.
El estándar que sugiere la mejor manera de utilizar los doctrings en python es el PEP 257 y fue creado por Guido van Rossum, el creador del lenguaje, junto con David Goodger.
Formato
El formato de los doctrings es una cadena de caracteres que se pone al inicio de
un módulo, antes de importar otros módulos, o inmediatamente después de definir
una clase o función. La convención indica que debe ser una cadena de caracteres
rodeada por 3 comillas dobles """.
Ejemplos:
:mod:`csv` --- CSV File Reading and Writing
===========================================
.. module:: csv
:synopsis: Write and read tabular data to and from delimited files.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. versionadded:: 2.3
.. index::
single: csv
pair: data; tabular
The so-called CSV (Comma Separated Values) format is the most common import and
export format for spreadsheets and databases...
Este es un fragmento del doctring del módulo csv. Lleva además ciertas
convenciones de formato para poder ser leído como REstructured Text. Un ejemplo
mas sencillo es la documentación de la función modf
.. function:: modf(x)
Return the fractional and integer parts of *x*. Both results carry the sign
of *x* and are floats.
Como se puede ver la documentación de python tiene la convención de utilizar Restructured Text como formato, pero dependiendo de la complejidad de la función o del nivel al que queramos describir puede ser de múltiples líneas o estar incluída en una sóla línea.
Es importante notar que aunque sea de una sola línea, el doctring comienza con mayúsculas y termina en punto.
Las doctrings multi línea en general son mas descriptivas y contienen la fecha de creación, versionamiento, autores, tipos de datos de entrada y tipos de dato de salida.
Aparte de un texto descriptivo del problema que resuelven y algunas veces la estructura de datos utilizada. Muchas veces es importante buscar en el doctring el tipo de errores y excepciones arrojadas por el uso equivocado de las funciones o clases.
Tipos de formatos populares en doctrings
| Tipo | Descripción |
|---|---|
| Numpy/Scipy | Combinación de reStructured Text y GoogleDocstrings |
| Pydoc | Documentación estándar de python y soportado por Sphinx |
| Google Docstrings | Estándar de documentación de Google |
Sphinx
El estilo mas común o mas aceptado es el estilo de Sphinx, es fácil y tradicional, con texto abundante y fue creado específicamente para la documentación de python. Sphinx utiliza reStructuredText que es un lenguaje de markdown.
Estilo Google
El estilo de Google es mas sencillo e intuitivo, puede ser utilizado para la forma mas breve de documentación. Para utilizarlo se debe añadir una extensión a conf.py sphinx.ext.napoleon. Tiene el problema de que algunas partes mas extensas de la documentación pueden aparecer desordenadas, para esto, Numpy desarrolló un estándar de documentación mucho mas detallado.
Estilo Numpy
El estilo Numpy tiene muchos detalles en la documentación, es mas verboso que otros estilos, pero es una excelente elección si se necesita hacer una descripción detallada de las funciones y parámetros. Así como de los algoritmos y las excepciones. Algo muy importante en un proyecto de análisis numérico.
Conclusión
Existen diferentes estándares para documentar código que se va a reutilizar de manera significativa o incluso que se va a poner disponible al público en general como código abierto. Es muy importante que este código tenga documentación clara y esta se encuentre disponible de la manera estándar para que nuestro proyecto sea popular y sea utilizado por la mayor cantidad de gente posible. Un código que nadie entiende es un código que nadie usa.