Cómo comentar en Python – Consejos y mejores prácticas

Comentar tu código es una buena práctica si quieres ayudar a otras personas a entender lo que escribiste. Esto hace que aprender a comentar en Python sea fundamental si trabaja en un equipo grande.

Sin embargo, también es muy importante si quieres entender lo que tú tienes escrito en un tiempo futuro. Volver al código anterior puede ser confuso y eso es un problema si espera ofrecer soporte continuo para una aplicación.

Lea también: Cómo usar cadenas en Python

En esta publicación, veremos cómo comentar en Python y cómo comentar 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 tienes que anteponer un hashtag a lo que vayas a escribir:

Código

#This is a comment!

De esta manera, el intérprete ignorará todo lo que haya escrito y lo resaltará para cualquiera que vea su código. Puede poner un comentario de Python en su línea o incluso en línea con el código que desea explicar.

Entonces, aprender a comentar en Python es fácil; la parte difícil es saber cuándo comentar y cómo asegurarse de que los comentarios sean legibles y útiles.

Lea también: Cómo imprimir en Python

Una forma de lograr esto es asegurarse de que sus comentarios sigan las mejores prácticas básicas. De acuerdo a Guía de estilo para código Python, debe tratar de mantener sus comentarios por debajo de 79 caracteres por línea. Esto evita que el lector tenga que desplazarse horizontalmente y mantiene todo en orden.

Si bien los comentarios en línea pueden ser útiles, tenga en cuenta que colocarlos consecutivamente puede dificultar saber qué es 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:

Código

if baddy_x + 40 > mine_x and baddy_y + 40 > mine_y and baddy_x < mine_x + 0 and baddy_y < mine_y + 19: #Checks the position of the bad guy in relation to the mine
          baddy_x = 10000 #Sets the position of the bad guy to be far off the screen out of site 
          pygame.display.update() #Updates the graphics reflecting the new positions

      for event in pygame.event.get(): #Looks for an event 
            if event.type == pygame.QUIT: #If the event is the player clicking the cross
                  run = False

Una manera mucho mejor de obtener algo como esto sería:

Código

#If the baddy overlaps the mine, then the baddy is sent off page and the graphics update. Then we will check for events.
      
      if baddy_x + 40 > mine_x and baddy_y + 40 > mine_y and baddy_x < mine_x + 0 and baddy_y < mine_y + 19: 
          baddy_x = 10000 
          pygame.display.update() 

      for event in pygame.event.get(): 
            if event.type == pygame.QUIT: 
                  run = False

¡Pero claro, uno de ellos sería un ejemplo de comentarios inútiles!

Cuándo y cómo comentar en Python

En cuanto a lo que hay que comentar…

Algunos títulos comunes y útiles para agregar a su código incluyen:

  • Un poco sobre las características nuevas y lo que hace
  • Una explicación de la utilidad de una variable o conjunto de variables
  • Explique por qué hizo algo de cierta manera (si no es obvio)
  • Resaltar partes clave e 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: ¡respete el tiempo de su lector!
  • Evite comentarios que digan lo obvio; No Sobre comentario
  • no solo expliques qué algo hace: explicar Por qué lo pones ahí y por qué importa
  • ¡Sé amable y amistoso! Absolutamente no uses comentarios para avergonzar a otros programadores. Es una forma rápida de convertirte en la persona menos popular de tu equipo.

Otros usos para los comentarios de Python

El uso principal para aprender a comentar en Python es proporcionar orientación e instrucciones útiles. Esto puede ayudar a otros a navegar por el código. Dicho esto, sin embargo, existen otros escenarios en los que el uso de código puede ser útil.

Lea también: Cómo crear un archivo en Python y más

Los comentarios de encabezado, por ejemplo, van al principio de un archivo y pueden ayudar a explicar qué hace el código subyacente. Esto también puede incluir algunos consejos útiles que ayudarán al lector a encontrar funciones importantes.

Los comentarios del encabezado también se pueden usar como un espacio para insertar un aviso de derechos de autor o para declarar su autoría del código. A algunas personas les gusta usar ASCII exagerado para darle a su código títulos extravagantes.

Codificación ocular

Otro uso de los comentarios de Python es ayudarlo a encontrar su código rápidamente con la herramienta de búsqueda. A menudo me dejo comentarios a mí mismo para poder saltar rápidamente entre diferentes lugares en mi código o como una forma de marcar algo que debo hacer a continuación. Si dejo algo sin terminar, a menudo comento allí para poder encontrarlo fácilmente más tarde.

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? Encuentro que la programación puede ser un trabajo solitario y, a veces, encontrar un poco de espíritu ingenioso o un “hola” puede levantar el ánimo.

¡No cuesta nada ser agradable!

Pensamientos finales

Tenga en cuenta que saber cómo comentar en Python no lo exime de tener que escribir un código limpio y legible. ¡Sus comentarios deben servir como una guía adicional útil para los lectores, no como una piedra de Rosetta para descifrar sus locas divagaciones!

Esto significa que también debe:

  • Estructura tu código lógicamente
  • Use nombres inteligentes para variables y funciones, junto con una convención de nomenclatura coherente
  • Usando nuevas líneas y sangrías correctamente (afortunadamente, Python nos obliga a hacer esto último)

Hay quienes creen que comentar el código es en realidad una indicación de que, para empezar, el código no se escribió bien. ¡Esa multitud en realidad predica en contra del uso de comentarios!

En última instancia, la moderación o la generosidad con la que elija comentar su código es una cuestión de preferencia personal. Pero tenga en cuenta que es posible que alguien que mire su código no tenga tanta experiencia como usted, ¡y una pequeña guía podría ser de gran ayuda! El objetivo principal es garantizar que cualquier persona que necesite entender su código pueda hacerlo y, mientras lo haga, ¡depende de usted decidir cómo hacerlo!

Aquí se explica cómo comentar en Python. ¿Qué encuentras ú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. Echa un vistazo a nuestro desglose de las mejores opciones.


Para obtener más noticias, funciones y tutoriales para desarrolladores de Android Authority, ¡no deje de suscribirse al boletín mensual a continuación!

Compruebe también

Nuevos gadgets de Android y wearables en el Mobile World Congress + ¡Sintoniza un nuevo episodio de #TheAndroidShow la próxima semana!

Publicado por Anirudh Dewani, Director de Relaciones con Desarrolladores de Android Hoy, en el Mobile …

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *