Читать книгу Python a fondo - Óscar Ramírez Jiménez - Страница 30

PEP-8 es bastante explícito a la hora de definir las reglas de cómo deberían ser los comentarios del código:

• Es mucho mejor no tener comentarios que tener comentarios que contradigan el código.

• Los comentarios deben de estar compuestos de una o varias frases completas, terminar con un punto al final y comenzar con mayúsculas, a no ser que comiencen con un identificador que esté en minúscula, en ese caso, se respetará siempre la forma en que esté escrito el identificador.

• Para programadores de habla distinta a la inglesa, se ruega que escriban los comentarios en inglés a no ser que estén 120 % seguros de que cualquier otro desarrollador que lea el código sabrá su idioma.

• Los bloques de comentarios afectan al código que está indentado al mismo nivel que el bloque de comentarios, y entre párrafo y párrafo habrá que añadir dos líneas en blanco.

• Los comentarios de una sola línea deberán usarse de forma moderada, los añadidos tras la línea de código se harán añadiendo dos espacios, los caracteres "# " detrás de la línea en la que se desea añadir el comentario y solo se añadirán si el objetivo de la línea de código no es obvio en sí mismo.

• Para la documentación de código (docstrings) se utilizarán siempre los tres caracteres seguidos """ para abrir y cerrar el bloque de comentarios.

• Los módulos públicos, funciones, clases y métodos deben tener un docstring (documentación de código) y solo los métodos privados pueden no tenerlo, aunque deben tener un comentario justo después de la definición de la cabecera del mismo.