Header Ads Widget

Ticker

6/recent/ticker-posts

Cómo comentar código en Python: en línea, multilínea y Docstring

 Al comenzar 2020, quería comenzar a volver a algunos de mis contenidos favoritos: el contenido de Python "cómo hacer". Hoy veremos cómo comentar código en Python, una habilidad que todos deberíamos tener.

Para resumir, hay tres formas principales de hacer comentarios en Python. Para hacer comentarios en línea, utilice el símbolo de almohadilla, #Para hacer comentarios de varias líneas, use una marca de almohadilla en cada línea. Como alternativa, utilizar comillas triples, """Estos inician una cadena de varias líneas que se puede utilizar para simular comentarios. Para obtener más detalles, consulte las opciones a continuación.

Descripción del problema

Una cosa que he hecho a lo largo de esta serie es crear contenido que se enfoca en un problema específico y abordarlo con algunas soluciones. Por supuesto, muchas de esas soluciones requieren una comprensión fundamental de cómo funciona Python. En otras palabras, en ningún momento he escrito ninguno de esos artículos fundamentales. Bueno, supongo que es mejor tarde que nunca.

Hoy, quiero ver algunas formas de comentar código en Python. Para aquellos que no lo saben, los comentarios son formas de documentar el código directamente. Específicamente, un comentario es texto que no tiene ningún efecto semántico en sus programas. En otras palabras, los comentarios no hacen nada más que proporcionar contexto para el lector.

Como ejemplo, podríamos querer escribir alguna expresión matemática como el Teorema de Pitágoras:

1
2
3
a_squared = 3**2
b_squared = 4**2
c_squared = a_squared + b_squared

Claramente, esta expresión se parece al Teorema de Pitágoras basado únicamente en la elección de nombres de variables. Sin embargo, no todo el mundo podrá saberlo a primera vista. En otras palabras, podríamos querer agregar un comentario que le diga al lector cuál es el propósito de esta expresión. Por ejemplo, podríamos decir "usa el Teorema de Pitágoras para calcular c ^ 2". ¿Cómo lo hacemos? Afortunadamente, este artículo nos dará algunas opciones.

Soluciones

En esta parte del artículo, veremos algunas formas diferentes de escribir comentarios en Python. Tenga en cuenta que este no es realmente un artículo sobre estilos de comentarios o incluso un comentario sobre cómo escribir comentarios. En cambio, solo compartiremos la sintaxis. Depende de usted averiguar cómo desea utilizar las herramientas proporcionadas.

Comentarios en línea

En Python, se puede crear un comentario mediante el símbolo de almohadilla, #Tan pronto como aparece esta marca, todo lo que sigue hasta el final de la línea se considera un comentario:

1
2
3
4
# Uses the Pythagorean Theorem to compute c^2
a_squared = 3**2
b_squared = 4**2
c_squared = a_squared + b_squared

Dado que los comentarios no comienzan hasta que aparece la marca de almohadilla, también podemos comentar los finales de las líneas:

1
2
3
4
# Uses the Pythagorean Theorem to compute c^2
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

Normalmente, creo que su código debe ser principalmente autodocumentado. Dicho esto, un comentario en línea aquí y allá puede ser útil para futuros lectores, incluido usted mismo.

Bloquear comentarios usando comentarios en línea

Dato curioso: Python no tiene comentarios en bloque . En otras palabras, no existe una sintaxis incorporada para manejar comentarios de varias líneas. Como resultado, PEP 8 recomienda usar comentarios en línea repetidos para los comentarios de bloque:

1
2
3
4
5
6
7
# Uses the Pythagorean Theorem to compute c^2.
# First, we compute a^2 and b^2. Then, the
# expression is constructed as a^2 + b^2 and
# assigned to c^2.
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

Una vez más, estos comentarios probablemente sean excesivos; su función es proporcionar un ejemplo de un comentario de bloque.

Bloquear comentarios mediante cadenas de varias líneas

Con todo lo dicho, es posible simular comentarios de bloque con cadenas de varias líneas:

1
2
3
4
5
6
7
8
9
"""
Uses the Pythagorean Theorem to compute c^2.
First, we compute a^2 and b^2. Then, the
expression is constructed as a^2 + b^2 and
assigned to c^2.
"""
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

Ahora, eso me parece un poco más limpio. Además, en mi opinión, es un poco más fácil de administrar en código fuente.

Dicho esto, tenga en cuenta que este no es un comentario verdadero. En su lugar, hemos creado una constante de cadena que no está asignada a una variable. En la práctica, esto no es realmente un problema, ya que las cadenas se optimizarán en el código de bytes.

Otra advertencia: a veces este estilo de comentario se puede interpretar como una cadena de documentación. Por ejemplo, si insertamos este comentario justo debajo del encabezado de una función, habremos creado una cadena de documentos con fines de documentación:

1
2
3
4
5
6
7
8
def pythagorean_theorem(a, b):
  """
  Computes the length of the squared third leg of a right triangle.
  """
  a_squared = a**2
  b_squared = b**2
  c_squared = a_squared + b_squared
  return c_squared

En este ejemplo, nuestro comentario de varias líneas es en realidad una cadena de documentos que podemos usar para documentar el método:

01
02
03
04
05
06
07
08
09
10
11
def pythagorean_theorem(a, b):
  """
  Computes the length of the squared third leg of a right triangle.
  :param a: the length of the first leg of the triangle
  :param b: the length of the second leg of the triangle
  :return: a^2 + b^2
  """
  a_squared = a**2
  b_squared = b**2
  c_squared = a_squared + b_squared
  return c_squared

Entonces, esta cadena de documentos se convierte en un atributo de tiempo de ejecución de la función. En otras palabras, podemos inspeccionar ese atributo de la siguiente manera:

1
print(pythagorean_theorem.__doc__)

Como puede ver, las cadenas de documentos no son como comentarios en el sentido de que las cadenas de documentos todavía existen en tiempo de ejecución; los comentarios regulares no. Muchos IDE y otras herramientas pueden extraer estas cadenas de documentos con fines de documentación. ¿Cuan genial es eso?

Desafío

En este punto, normalmente mediría el rendimiento, pero no sentí que eso fuera aplicable. En cambio, ¡saltemos directamente al desafío!

Ahora que conocemos tres formas diferentes de comentar código en Python, hablemos de las buenas prácticas para comentar. En los comentarios a continuación, comparta al menos un consejo que recomiende cuando se trata de comentar código. No dude en compartir cualquier cosa, desde comentar estilos hasta comentar etiqueta. Puntos de bonificación para cualquier cosa que sea específica de Python.

Como siempre, también compartiré mi propio consejo a continuación. Si es posible, me encantaría entablar una pequeña conversación. Dependiendo de cómo vaya, podría recopilar los resultados en otro artículo.

Un pequeño resumen

Y con eso, hemos terminado. Como siempre, aquí hay un pequeño resumen de nuestras tres formas de comentar el código Python:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
# Here is an inline comment in Python
 
# Here
# is
# a
# multiline
# comment
# in
# Python
 
"""
Here is another multiline comment in Python.
This is sometimes interpretted as a docstring,
so be careful where you put these.
"""

Publicar un comentario

0 Comentarios