Guía completa para documentar código Python

· Programación

  1. La documentación es crucial porque 'el código se lee más de lo que se escribe' (Guido van Rossum) y sin buena documentación la gente no usará el software (Daniele Procida).
  2. Comentarios: para desarrolladores, explican el 'porqué' del código. Deben ser breves (máx. 72 caracteres) y seguir reglas como estar cerca del código que describen.
  3. Documentación con docstrings: para usuarios, usando triple comilla. Deben incluir resumen, descripción de parámetros, retornos y excepciones.
  4. Formatos comunes: Google, reStructuredText, NumPy/SciPy y Epytext. Se debe mantener consistencia en el proyecto.
  5. Estructura recomendada para proyectos: README, HOW_TO_CONTRIBUTE, CODE_OF_CONDUCT, LICENSE y carpeta docs con tutoriales, guías, referencias y explicaciones.

desarrollo software · buenas practicas · python · documentacion · docstrings

Leer el original

Más en Programación