Página
Tema 3.3 – Comentarios
Los comentarios que contradicen el código son peores que no tener algún comentario. Siempre tenga el cuidado de mantener los comentarios actualizados cuando cambie el código.
Los comentarios deben ser oraciones completas. La primera palabra debe estar en mayúscula, a menos que sea un identificador que comience con una letra minúscula (nunca modifique la letra minúscula para el caso de los identificadores).
Los comentarios de bloque generalmente consisten en uno o más párrafos construidos con oraciones completas, y cada oración debe finalizar con un punto.
Debe usar dos espacios después de que una oración termine con un punto para comentarios de varias oraciones, excepto para la oración final.
Los programadores de Python de países que no son de habla inglesa deben escribir sus comentarios en inglés, a menos que esté 100% seguro de que el código nunca será leído por personas que no hablen su idioma.
Comentarios en bloque
Los comentarios en bloque generalmente se aplican a algunos (o todos) códigos que los siguen, y están indentados al mismo nivel que ese código. Cada línea de un comentario de bloque comienza con un # (numeral) y un solo espacio (a menos que esté indentado dentro del mismo comentario).
Los párrafos dentro de un comentario en bloque están separados por una línea que contiene un solo #.
Comentarios en línea
Utilice comentarios en línea con moderación.
Un comentario en línea es aquel que se encuentra en la misma línea que una sentencia. Los comentarios en línea deben estar separados por al menos dos espacios de la sentencia. Deben comenzar con un # seguido de un espacio.
Los comentarios en línea son innecesarios y de hecho son molestos si dicen lo obvio. No haga esto:
1 |
x = x + 1 # Incrementar x |
Pero a veces, esto es útil:
1 |
x = x + 1 # Compensar el borde |
Cadenas de documentación
Las convenciones para escribir buenas cadenas de documentación (también conocidas como "docstrings") sé definidas en PEP 257.
Los docstrings, se pueden escribir para todos los módulos, funciones, clases y métodos públicos. Los docstrings no son necesarios para los métodos no públicos, pero deben tener un comentario que describa su función. Este comentario debería estar después de la línea de definición, el “def”.
Tenga en cuenta que lo más importante para los docstrings es que él""" que finaliza un docstring multilínea debe ocupar una línea por sí mismo:
1 2 3 4 | """Return a foobang Optional plotz says to frobnicate the bizbaz first. """ |
Última modificación: miércoles, 16 de marzo de 2022, 13:15