Breaking

Post Top Ad

Your Ad Spot

viernes, 14 de junio de 2019

Comentando el código de Python

La programación refleja su forma de pensar para describir los pasos individuales que tomó para resolver un problema usando una computadora. El 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.
Los comentarios son importantes 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 ser confusas, muy rápido. En este artículo explicaremos los diversos métodos para comentar los apoyos de Python y cómo se puede usar para crear automáticamente la documentación de su código utilizando las denominadas cadenas de documentación de nivel de módulo.

Comentarios buenos contra malos

Tan importante como son los comentarios, todavía es posible escribir malos comentarios. Siempre deben ser cortos, directos al punto, 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 le da nombres obvios a las variables:
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 una sección de código cuyo propósito no sea obvio. Esto es muy subjetivo, y en realidad es una habilidad que necesita ser aprendida.

Tipos de comentarios

Un comentario en Python comienza con el carácter de 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 formas: 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 de hash ( #) y es seguido por un texto que contiene explicaciones adicionales.
# defining the post code
postCode = 75000  
También puede escribir un comentario al lado de 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 el 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, querrá extenderlo en varias líneas.

Comentarios multilínea

Como ya se mencionó anteriormente, Python también comprende un bloque de comentarios completo. Estos comentarios sirven como documentación en línea para que otros lean 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 algunos consideran que las siguientes opciones son una solución alternativa, pero aún funcionan con el propósito de comentarios de varias líneas.
La versión 1 combina los 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 fue diseñada para usarse para crear documentación (vea más sobre esto más adelante), pero también se puede usar 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 que funcionen, y no con caracteres hash.

Práctica común

Es bastante común comenzar un archivo de Python con algunas líneas de comentarios. Estas líneas indican 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 usa para el código.
Este fragmento de código está tomado de uno de los ejemplos que uso para fines de capacitación. El comentario comienza con la descripción, seguido del aviso de copyright con mi nombre y el año de publicación del código. A continuación, verá que el código está licenciado bajo la Licencia Pública GNU ( GPL ). Para contactarme, mi dirección de correo electrónico se agrega allí también.
# -----------------------------------------------------------
# demonstrates how to write ms excel files using python-openpyxl
#
# (C) 2015 Frank Hofmann, Berlin, Germany
# Released under GNU Public License (GPL)
# email frank.hofmann@efho.de
# -----------------------------------------------------------

Comentarios Docstring

Python tiene un concepto incorporado llamado 'docstrings', que es una excelente manera de asociar la documentación que ha escrito con los módulos, funciones, clases y métodos de Python. Una cadena de documentos se agrega como un comentario justo debajo de la función, el módulo o el encabezado del objeto, y describe lo que hace la función, el módulo o el objeto. Se espera que siga estas reglas:
  • Una cadena de documentos 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 documentos con una letra mayúscula y finalícela 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 se pone a disposición 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 la documentación de las cadenas de documentación, como Doxygen , PyDoc , pdoc y la extensión autodoc para Sphinx. Le explicaremos cómo trabajar con ellos en un artículo de seguimiento.

Conclusión

Escribir los comentarios apropiados en tu código Python no es tan complicado, y solo necesitas 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 el consejo que le brindamos aquí le facilite la creación de mejores comentarios y documentación en su código.

Expresiones de gratitud

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

No hay comentarios.:

Publicar un comentario

Dejanos tu comentario para seguir mejorando!

Post Top Ad

Your Ad Spot

Páginas