U6.3 · Comentarios y documentación

Un buen comentario explica el porqué, no repite lo que ya dice el código. La documentación de clases y funciones se escribe con el formato de cada lenguaje y se convierte en páginas web con una herramienta.

Ejercicio 6.11

Documenta tu código. Toma las clases de la biblioteca de medios (ejercicios 6.1 y 6.2) y añade documentación a todas las clases públicas y a sus métodos: qué hace, qué recibe, qué devuelve y qué excepciones puede lanzar. Incluye al menos un ejemplo de uso.

En Python

Docstrings con triple comilla justo debajo de la definición (estilo Google o NumPy).

Ejercicio 6.12

Genera la documentación. Ejecuta la herramienta de tu lenguaje para crear la documentación en HTML, ábrela en el navegador y revisa si se entiende sin mirar el código. Corrige lo que no quede claro.

En Python

Usa python -m pydoc -w modulo o Sphinx/pdoc (pip install pdoc y pdoc modulo).

Ejercicio 6.13

Comentarios que sobran. Dado este fragmento, elimina los comentarios inútiles, mejora los que aporten algo y renombra lo que haga falta para que el código se explique solo:

// incrementa i
i = i + 1
// si x es mayor que 18
if x > 18:
    // imprime mayor
    print("mayor")
// variable para el precio
p = 10