Python/Su primer programa en Python/Documentado de funciones

Índice de la sección
«Su primer programa en Python»

1. Inmersión
2. Preguntas y respuestas
3. Ecuación de segundo grado en Python
4. Declaración de funciones
5. Cómo se comparan los tipos de Python con los de otros lenguajes de programación
6. Documentado de funciones
7. Todo es un objeto
8. ¿Qué es un objeto?
9. La ruta de búsqueda de import
10. Sangrado (indentado) de código
11. Prueba de módulos

Puede documentar una función en Python proporcionando una cadena de documentación (en español se les suele llamar comentarios).

Ejemplo 2.2. Definición de la cadena de documentación de la función buildConnectionString

 def buildConnectionString(params):
     """Crea una cadena de conexión partiendo de un diccionario de parámetros.
 
     Devuelve una cadena."""

Las comillas triples implican una cadena multilínea. Todo lo que haya entre el principio y el final de las comillas es parte de una sola cadena, incluyendo los retornos de carro y otras comillas. Puede usarlas para definir cualquier cadena, pero donde las verá más a menudo es haciendo de cadena de documentación.

Nota: Las comillas triples también son una manera sencilla de definir una cadena que contenga comillas tanto simples como dobles, como qq/.../ en Perl.

Todo lo que hay entre las comillas triples es la cadena de documentación de la función, y se usa para explicar lo que hace la función. En caso de que exista una cadena de documentación, debe ser la primera cosa definida en una función (esto es, lo primero tras los dos puntos). Técnicamente, no necesita dotar a su función de una cadena de documentación, pero debería hacerlo siempre. Sé que habrá escuchado esto en toda clase de programación a la que haya asistido alguna vez, pero Python le da un incentivo añadido: la cadena de documentación está disponible en tiempo de ejecución como atributo de la función.

Nota: Muchos IDE de Python utilizan la cadena de documentación para proporcionar una ayuda sensible al contexto, de manera que cuando escriba el nombre de una función aparezca su cadena de documentación como ayuda. Esto puede ser increíblemente útil, pero lo será tanto como buenas las cadenas de documentación que usted escriba.

Lecturas complementarias sobre las funciones de documentación

• PEP 257 define las convenciones al respecto de las cadenas de documentación.
• La Guía de estilo de Python indica la manera de escribir una buena cadena de documentación.
• El Tutorial de Python expone convenciones para el espaciado dentro de las cadenas de documentación.

---