Comentar el código de Python

C

La programación refleja su forma de pensar para describir los pasos individuales que siguió para resolver un problema utilizando una computadora. Comentar su código ayuda a explicar su proceso de pensamiento y le ayuda a usted y a otros a comprender más adelante la intención de su código. Esto le permite encontrar errores más fácilmente, corregirlos, mejorar el código más adelante y reutilizarlo también en otras aplicaciones.

Comentar es importante para todo tipo de proyectos, sin importar si son pequeños, medianos o bastante grandes. Es una parte esencial de su flujo de trabajo y se considera una buena práctica para los desarrolladores. Sin comentarios, las cosas pueden volverse confusas, muy rápido. En este artículo, explicaremos los diversos métodos de comentarios que admite Python y cómo se puede utilizar para crear automáticamente documentación para su código utilizando las denominadas cadenas de documentación a nivel de módulo.

Comentarios buenos y malos

Por importantes que sean los comentarios, aún es posible escribir comentarios negativos. Siempre deben ser breves, ir al grano y agregar valor informativo.

Por ejemplo, este es un comentario bastante inútil:

b = 56                       # assigning b a value of 56

El siguiente ejemplo muestra un comentario más útil, en cambio, y sigue dando a las variables nombres obvios:

salestax10 = 1.10            # defining a sales tax of 10%
salestax20 = 1.20            # defining a sales tax of 20%

Hay un número infinito de otros escenarios que merecen comentarios. Esto es sólo un ejemplo. Una buena regla general sería agregar comentarios para cualquier línea de código (como una lista de comprensión) o sección de código cuyo propósito no sea obvio. Esto es muy subjetivo y en realidad es una habilidad que debe aprenderse.

Tipos de comentarios

Un comentario en Python comienza con el carácter hash, #y se extiende hasta el final de la línea física. Sin embargo, un carácter hash dentro de un valor de cadena no se considera un comentario. Para ser precisos, un comentario se puede escribir de tres maneras: completamente en su propia línea, junto a una declaración de código y como un bloque de comentarios de varias líneas.

En las siguientes secciones describiré cada tipo de comentario.

Comentarios de una sola línea

Dicho comentario comienza con un carácter hash (#) y va seguido de un texto que contiene más explicaciones.

# defining the post code
postCode = 75000

También puede escribir un comentario junto a una declaración de código. El siguiente ejemplo muestra que:

# define the general structure of the product with default values
product = {
    "productId": 0,          # product reference id, default: 0
    "description": "",       # item description, default: empty
    "categoryId": 0,         # item category, default: 0
    "price": 0.00            # price, default: 0.00
}

La guía de estilo para código Python (PEP8) recomienda menos de 79 caracteres por línea. En la práctica, 70 o 72 caracteres por línea son más fáciles de leer, por lo que se recomienda. Si su comentario se acerca o excede esta longitud, entonces querrá distribuirlo en varias líneas.

Comentarios de varias líneas

Como ya se mencionó anteriormente, Python también entiende un bloque de comentarios completo. Estos comentarios sirven como documentación en línea para otros que leen su código y, por lo general, explican las cosas con más detalle.

Técnicamente, Python no tiene soporte explícito para comentarios de varias líneas, por lo que algunas personas consideran que las siguientes opciones son una solución alternativa, pero aún funcionan para los comentarios de varias líneas.

La versión 1 combina comentarios de una sola línea de la siguiente manera:

# LinuxThingy version 1.6.5
#
# Parameters:
#
# -t (--text): show the text interface
# -h (--help): display this help

La versión 2 es más simple que la versión 1. Originalmente está pensada para ser utilizada para crear documentación (ver más sobre esto a continuación), pero también se puede utilizar para comentarios de varias líneas.

"""
LinuxThingy version 1.6.5

Parameters:

-t (--text): show the text interface
-h (--help): display this help
"""

Tenga en cuenta que la última versión debe incluirse entre comillas especiales (""") para trabajar, y no caracteres hash.

Práctica común

Es bastante común iniciar un archivo Python con algunas líneas de comentarios. Estas líneas contienen información sobre el proyecto, el propósito del archivo, el programador que lo desarrolló o ha trabajado en él y la licencia de software que se utiliza para el código.

Este fragmento se tomó de uno de los ejemplos que utilizo con fines de capacitación. El comentario comienza con la descripción y va seguido del aviso de derechos de autor con mi nombre y el año de publicación del código. A continuación, verá que el código tiene una licencia pública GNU (GPL). Para contactarme, también se agrega mi dirección de correo electrónico.

# -----------------------------------------------------------
# demonstrates how to write ms excel files using python-openpyxl
#
# (C) 2015 Frank Hofmann, Berlin, Germany
# Released under GNU Public License (GPL)
# email [email protected]
# -----------------------------------------------------------

Comentarios de la cadena de documentos

Python tiene un concepto incorporado llamado docstrings, que es una excelente manera de asociar la documentación que ha escrito con módulos, funciones, clases y métodos de Python. Se agrega una cadena de documentos como comentario justo debajo de la función, módulo o encabezado del objeto, y describe lo que hace la función, módulo u objeto. Se espera que siga estas reglas:

  • Una cadena de documentos es una sola línea o un comentario de varias líneas. En el último caso, la primera línea es una descripción breve y después de la primera línea sigue una línea vacía.
  • Comience la cadena de documentos con una letra mayúscula y termínela con un punto.

Este es un ejemplo básico de cómo se ve:

def add(value1, value2):
    """Calculate the sum of value1 and value2."""
    return value1 + value2

En el sistema de ayuda interactiva de Python, la cadena de documentos está disponible a través del __doc__ atributo.

>>> print add.__doc__
Calculate the sum of value1 and value2.

Hay una serie de herramientas que generan automáticamente documentación a partir de cadenas de documentos, como Doxygen, PyDoc, pdoc, y el autodoc extensión para Sphinx. Te explicaremos cómo trabajar con ellos en un artículo de seguimiento.

Conclusión

Escribir comentarios adecuados en su código Python no es tan complicado y solo necesita el poder de la resistencia. Nos ayuda a todos los que intentamos comprender su código, incluido usted mismo para cuando vuelva a visitar su código en una fecha posterior. Esperamos que los consejos que le hemos dado aquí le faciliten la creación de mejores comentarios y documentación en su código.

 

About the author

Ramiro de la Vega

Bienvenido a Pharos.sh

Soy Ramiro de la Vega, Estadounidense con raíces Españolas. Empecé a programar hace casi 20 años cuando era muy jovencito.

Espero que en mi web encuentres la inspiración y ayuda que necesitas para adentrarte en el fantástico mundo de la programación y conseguir tus objetivos por difíciles que sean.

Add comment

Sobre mi

Últimos Post

Etiquetas

Esta web utiliza cookies propias para su correcto funcionamiento. Al hacer clic en el botón Aceptar, aceptas el uso de estas tecnologías y el procesamiento de tus datos para estos propósitos. Más información
Privacidad