Comentando el código de Python

La programación refleja tu forma de pensar para describir los pasos individuales que tomaste para resolver un problema usando una computadora. Comentar tu código ayuda ex...

La programación refleja tu forma de pensar para describir los pasos individuales que tomaste para resolver un problema usando una computadora. Comentar su código ayuda a explicar su proceso de pensamiento y lo 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 para comentar los soportes de Python y cómo se puede usar para crear automáticamente documentación para su código usando las llamadas 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, directos al grano y agregar valor informativo.

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

1
b = 56                       # assigning b a value of 56

En cambio, el siguiente ejemplo muestra un comentario más útil y va junto con dar nombres obvios a las variables:

1
2
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 ve como 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.

1
2
# 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:

1
2
3
4
5
6
7
# 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 y, por lo tanto, se recomiendan. Si su comentario se acerca o supera esta longitud, 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 otras personas 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 opciones 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:

1
2
3
4
5
6
# 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, se diseñó para crear documentación (vea más sobre esto a continuación), pero también se puede usar para comentarios de varias líneas.

1
2
3
4
5
6
7
8
"""
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 estar encerrada entre comillas especiales (""") para funcionar, y no con caracteres hash.

Práctica común

Es bastante común comenzar un archivo de Python con unas pocas 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 del software que se utiliza para el código.

Este fragmento está tomado de uno de los ejemplos que uso con fines de capacitación. El comentario comienza con la descripción y le sigue el aviso de copyright con mi nombre y el año de publicación del código. A continuación, verá que el código tiene licencia pública GNU (GPL). Para contactarme, mi dirección de correo electrónico también se agrega allí.

1
2
3
4
5
6
7
# -----------------------------------------------------------
# demonstrates how to write ms excel files using python-openpyxl
#
# (C) 2015 Frank Hofmann, Berlin, Germany
# Released under GNU Public License (GPL)
# email [correo electrónico protegido]
# -----------------------------------------------------------

Comentarios de cadena de documentación {#comentarios de cadena de documentación}

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

  • Una cadena de documentación es una sola línea o un comentario de varias líneas. En este último caso, la primera línea es una breve descripción, y después de la primera línea sigue una línea vacía.

  • Comience la cadena de documentación con una letra mayúscula y finalícela con un punto.

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

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

En el sistema de ayuda interactivo de Python, la cadena de documentación está disponible a través del atributo __doc__.

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

Hay una serie de herramientas que generan documentación automáticamente a partir de cadenas de documentos, como doxígeno, [PyDoc](https://docs.python.org/3/library/ pydoc.html), pdoc y [autodoc](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc .html) extensión para Esfinge. Le 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 estamos tratando de entender su código, incluido usted mismo, para cuando vuelva a revisar 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.

Agradecimientos

El autor desea agradecer a Zoleka Hofmann por sus comentarios críticos mientras preparaba este artículo.

Licensed under CC BY-NC-SA 4.0