Comentar tu código es una buena práctica si quieres ayudar a otras personas a entender lo que has escrito. Esto hace que sea crucial aprender a comentar en Python si trabajas en un gran equipo.
Sin embargo, también es muy importante si quieres entender qué tienes escrito en un punto en el futuro. Volver al código antiguo puede ser desorientador, y esto es un problema si espera ofrecer soporte continuo para una aplicación.
En esta publicación, veremos cómo comentar en Python y cómo hacerlo de una manera lógica y útil.
Cómo comentar en Python y hacerlo útil
La buena noticia es que es extremadamente fácil comentar en Python. Simplemente necesita prefijar lo que va a escribir con un hashtag:
#Esto es un comentario!
De esta manera, lo que haya escrito será ignorado por el intérprete y se resaltará para cualquiera que vea su código. Puede colocar un comentario de Python en su propia línea o incluso en línea con el código que desea explicar.
Aprender a comentar en Python es fácil, entonces; lo difícil es saber cuándo comentar y cómo garantizar que esos comentarios sean legibles y útiles.
Una forma de lograr esto es asegurando que sus comentarios sigan las mejores prácticas básicas. De acuerdo con la Guía de estilo para código Python, debe intentar mantener sus comentarios por debajo de 79 caracteres por línea. Esto evita que el lector necesite desplazarse horizontalmente y mantiene todo ordenado.
Si bien los comentarios en línea pueden ser útiles, tenga en cuenta que colocarlos consecutivamente puede dificultar saber qué es el código y qué no, lo que hace que sea mucho más difícil interpretar el programa de un vistazo.
Esto es confuso, por ejemplo:
if baddyX + 40 > mineX and baddyY + 40 > mineY and baddyX < mineX + 0 and baddyY < mineY + 19: #Comprueba la posición del malo en relación con la mina.
baddyX = 10000 #Establece la posición del malo para que esté lejos de la pantalla fuera del sitio
pygame.display.update() #Actualiza los gráficos que reflejan las nuevas posiciones.
for event in pygame.event.get(): #Busca un evento
if event.type == pygame.QUIT: #Si el evento es el jugador haciendo clic en la cruz
run = False
Una forma mucho mejor de lograr algo similar sería:
#Si el malo se superpone a la mina, entonces el malo se envía fuera de la página y los gráficos se actualizan. Entonces buscaremos eventos..
if baddyX + 40 > mineX and baddyY + 40 > mineY and baddyX < mineX + 0 and baddyY < mineY + 19:
baddyX = 10000
pygame.display.update()
for event in pygame.event.get():
if event.type == pygame.QUIT:
run = False
Pero, por supuesto, ¡cualquiera de estos sería un ejemplo de comentarios innecesarios!
Cuándo y cómo comentar en Python
En cuanto a lo que hay que comentar …
Algunos subtítulos comunes y útiles para agregar a su código incluyen:
- Un poco sobre cualquier función nueva y lo que hace
- Una explicación de para qué sirve una variable o conjunto de variables
- Explicar por qué has hecho algo de cierta manera (si no es obvio)
- Destacando la clave y partes importantes de su código
- Proporcionar advertencias
Algunos consejos útiles para mantener los comentarios útiles en lugar de distraer:
- Mantenga los comentarios concisos y no más de lo necesario: ¡sea respetuoso con el tiempo de su lector!
- Evite comentarios que indiquen lo obvio; no lo hagas encima comentario
- No solo expliques qué algo hace: explicar por qué lo pones ahí y por qué es importante
- ¡Sé cortés y amable! Absolutamente no use comentarios para avergonzar a otros codificadores. Esa es una forma rápida de convertirse en la persona menos popular en su equipo.
Más usos para los comentarios de Python
El uso principal para aprender a comentar en Python es proporcionar una guía e instrucción útiles. Esto puede ayudar a otros a navegar por el código. Dicho esto, sin embargo, hay otros escenarios en los que usar código puede ser útil.
Los comentarios de encabezado, por ejemplo, van al principio de un archivo y pueden ayudar a explicar lo que hace el código debajo. Esto incluso podría incluir algunas instrucciones útiles que ayudarán al lector a encontrar funciones importantes.
Los comentarios de encabezado también se pueden usar como un lugar para insertar un aviso de copyright o para declarar su autoría del código. A algunas personas les gusta usar ASCII exagerado para dar a sus códigos títulos extravagantes.
Otro uso para los comentarios de Python es ayudarlo a encontrar rápidamente su código con la herramienta de búsqueda. A menudo me dejo comentarios para poder saltar rápidamente entre diferentes puntos en mi código, o como una forma de marcar algo que necesito hacer más tarde. Si dejo algo sin terminar, a menudo comentaré allí para poder encontrarlo fácilmente más adelante.
Finalmente, puedes usar comentarios en Python para hacer bromas. Esto irritará a algunas personas y ciertamente no hará que su código sea lo más limpio y eficiente posible. ¿Pero personalmente? Me parece que la programación puede ser un trabajo solitario, y a veces encontrar un poco de ingenio o «hola» puede levantar el ánimo.
¡No cuesta nada ser amable!
Palabras finales
Tenga en cuenta que saber cómo comentar en Python no le exime de la necesidad de escribir código limpio y legible. Sus comentarios deberían servir como una guía adicional útil para los lectores, ¡no una piedra de Rosetta para decodificar sus divagaciones locas!
Esto significa que también deberías:
- Estructura tu código de manera lógica
- Utilice nombres inteligentes para variables y funciones, junto con una convención de nomenclatura coherente
- Usar nuevas líneas y muescas correctamente (afortunadamente, Python nos obliga a hacer lo último)
Hay quienes creen que comentar el código es en realidad una indicación de que, para empezar, el código no estaba bien escrito. ¡Esa multitud realmente predica contra el uso de comentarios por completo!
En última instancia, qué tan escasa o generosamente elijas comentar tu código es una cuestión de preferencia personal. Pero tenga en cuenta que alguien que mira su código puede no tener tanta experiencia como usted, ¡y un poco de orientación podría ser de gran ayuda! El objetivo principal es garantizar que cualquier persona que necesite comprender su código pueda, y siempre que sea así, ¡depende de usted cómo lo haga!
Así es como comentar en Python. ¿Qué le resulta útil / irritante al leer el código? ¿Hay algo que nos perdimos? ¡Háganos saber en los comentarios a continuación!
Si desea obtener más información sobre la codificación de Python, le recomendamos que pruebe un curso en línea. Esta es la mejor manera de familiarizarse rápidamente con un nuevo lenguaje de programación. Vea nuestro desglose de las mejores opciones.
