Crear comentarios de Python de la manera correcta

Los comentarios son notas que los programadores agregan a su código para explicar qué se supone que debe hacer ese código. Los compiladores o intérpretes que convierten el código en acción ignoran los comentarios, pero pueden ser esenciales para administrar proyectos de software.

Los comentarios ayudan a explicar su código de Python a otros programadores y pueden recordarle por qué tomó las decisiones que tomó. Los comentarios facilitan la depuración y revisión del código al ayudar a los futuros programadores a comprender las opciones de diseño detrás del software.

Aunque los comentarios son principalmente para desarrolladores, escribir comentarios efectivos también puede ayudar a producir una excelente documentación para los usuarios de su código. Con la ayuda de generadores de documentos como Sphinx para proyectos de Python, los comentarios en su código pueden proporcionar contenido para su documentación.

Miremos debajo del capó de comentar en Python.

Comentarios en Python

De acuerdo con la Guía de estilo de Python PEP 8, hay varias cosas a tener en cuenta al escribir comentarios:

• Los comentarios siempre deben ser oraciones completas y concisas.
• Es mejor no tener ningún comentario que uno que sea difícil de entender o inexacto.
• Los comentarios deben actualizarse regularmente para reflejar los cambios en su código.
• Demasiados comentarios pueden distraer y reducir la calidad del código. No se necesitan comentarios cuando el propósito del código es obvio.

En Python, una línea se declara como comentario cuando comienza con el símbolo # . Cuando el intérprete de Python encuentra # en su código, ignora cualquier cosa después de ese símbolo y no produce ningún error. Hay dos formas de declarar comentarios de una sola línea: comentarios en línea y comentarios en bloque.

Comentarios en línea

Los comentarios en línea proporcionan descripciones breves de variables y operaciones simples y se escriben en la misma línea que la declaración del código:

 border = x + 10 # Make offset of 10px

El comentario explica la función del código en la misma declaración que el código.

Bloquear comentarios

Los comentarios de bloque se utilizan para describir una lógica compleja en el código. Los comentarios de bloque en Python se construyen de manera similar a los comentarios en línea; la única diferencia es que los comentarios de bloque se escriben en una línea separada:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

Tenga en cuenta que al usar comentarios de bloque, los comentarios se escriben encima del código que están explicando. La Guía de estilo de Python PEP8 dicta que una línea de código no debe contener más de setenta y nueve caracteres, y los comentarios en línea a menudo superan esta longitud. Esta es la razón por la que se escriben comentarios de bloque para describir el código en líneas separadas.

Comentarios de varias líneas

Python no admite comentarios de varias líneas de forma nativa, lo que significa que no existe una disposición especial para definirlos. A pesar de esto, a menudo se utilizan comentarios que abarcan varias líneas.

Puede crear un comentario de varias líneas a partir de varios comentarios de una sola línea anteponiendo cada línea con # :

 # interpreter # ignores # these lines

También puede utilizar la sintaxis de cadenas de varias líneas. En Python, puede definir cadenas de varias líneas encerrándolas entre """ , triples comillas dobles o ''' , triples comillas simples:

 print("Multi-Line Comment") """ This String is Multi line """

En el código anterior, la cadena de varias líneas no está asignada a una variable, lo que hace que la cadena funcione como un comentario. En tiempo de ejecución, Python ignora la cadena y no se incluye en el código de bytes. Ejecutar el código anterior produce el siguiente resultado:

 Multi-Line Comment

Comentarios especiales

Además de hacer que su código sea legible, los comentarios también sirven para algunos propósitos especiales en Python, como la planificación de futuras adiciones de código y la generación de documentación.

Comentarios de la cadena de documentación de Python

En Python, las cadenas de documentación son comentarios de varias líneas que explican cómo usar una función o clase determinada. La documentación de su código se mejora mediante la creación de cadenas de documentación de alta calidad. Al trabajar con una función o clase y usar la función de help(obj) , las cadenas de documentación pueden ser útiles para brindar una descripción general del objeto.

Python PEP 257 proporciona un método estándar para declarar cadenas de documentos en Python, que se muestra a continuación:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

En el código anterior, la cadena de documentación proporcionó detalles sobre cómo funciona la función asociada. Con generadores de documentación como Sphinx, esta cadena de documentación se puede usar para brindarles a los usuarios de su proyecto una descripción general de cómo usar este método.

También se puede devolver una cadena de documentación definida justo debajo de la función o la firma de la clase mediante la función de help() . La función help() toma el nombre de un objeto o función como argumento y devuelve las cadenas de documentación de la función como salida. En el ejemplo anterior, se puede llamar a help(get_person) para revelar cadenas de documentos asociadas con la función get_person . Si ejecuta el código anterior en un shell interactivo usando el indicador -i , puede ver cómo Python analizará esta cadena de documentación. Ejecute el código anterior escribiendo python -i file.py .

La llamada a la función help(get_person) devuelve una cadena de documentación para su función. La salida contiene get_person(name, age, d=False) , que es una firma de función que Python agrega automáticamente.

El atributo get_person.__ doc__ también se puede usar para recuperar y modificar cadenas de documentos mediante programación. Después de agregar "Más información nueva" en el ejemplo anterior, aparece en la segunda llamada a help(get_person) . Aún así, es poco probable que necesite modificar dinámicamente cadenas de documentos en tiempo de ejecución como este.

TODO Comentarios

Al escribir código, hay ocasiones en las que querrá resaltar ciertas líneas o bloques completos para mejorar. Estas tareas están marcadas por comentarios TODO. Los comentarios TODO son útiles cuando está planeando actualizaciones o cambios en su código, o si desea informar a los usuarios o colaboradores del proyecto que quedan por escribir secciones específicas del código del archivo.

Los comentarios TODO no deben escribirse como pseudocódigo, solo tienen que explicar brevemente la función del código aún no escrito.

Los comentarios TODO y los comentarios de bloque de una sola línea son muy similares, y la única distinción entre ellos es que los comentarios TODO deben comenzar con un prefijo TODO:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

Es importante tener en cuenta que aunque muchos IDE pueden resaltar estos comentarios para el programador, el intérprete de Python no ve los comentarios TODO de manera diferente a los comentarios de bloque.

Mejores prácticas al escribir comentarios de Python

Hay una serie de mejores prácticas que deben seguirse al escribir comentarios para garantizar la confiabilidad y la calidad. A continuación se presentan algunos consejos para escribir comentarios de alta calidad en Python.

Evita lo obvio

Los comentarios que indican lo obvio no agregan ningún valor a su código y deben evitarse. Por ejemplo:

 x = x + 4 # increase x by 4

Ese comentario no es útil, ya que simplemente establece lo que hace el código sin explicar por qué debe hacerse. Los comentarios deben explicar el "por qué" en lugar del "qué" del código que describen.

Reescrito de manera más útil, el ejemplo anterior podría verse así:

 x = x + 4 # increase the border width

Mantenga los comentarios de Python breves y agradables

Mantenga sus comentarios cortos y fáciles de entender. Deben estar escritos en prosa estándar, no en pseudocódigo, y deben reemplazar la necesidad de leer el código real para obtener una descripción general de lo que hace. Demasiados detalles o comentarios complejos no facilitan el trabajo de un programador. Por ejemplo:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

El comentario anterior proporciona más información de la necesaria para el lector. En lugar de especificar la lógica principal, los comentarios deben proporcionar un resumen general del código. Este comentario se puede reescribir como:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Utilice los identificadores con cuidado

Los identificadores deben usarse con cuidado en los comentarios. Cambiar nombres de identificadores o casos puede confundir al lector. Ejemplo:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

El comentario anterior menciona class y argument , ninguno de los cuales se encuentra en el código. Este comentario se puede reescribir como:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

Seco y mojado

Cuando está escribiendo código, desea adherirse al principio DRY (no se repita) y evitar WET (escribir todo dos veces).

Esto también es cierto para los comentarios. Evite usar varias declaraciones para describir su código e intente fusionar comentarios que expliquen el mismo código en un solo comentario. Sin embargo, es importante tener cuidado al combinar comentarios: la combinación descuidada de múltiples comentarios puede resultar en un comentario enorme que viola las guías de estilo y es difícil de seguir para el lector.

Recuerda que los comentarios deben reducir el tiempo de lectura del código.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

En el código anterior, los comentarios se fragmentan innecesariamente y se pueden fusionar en un solo comentario:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

Sangría consistente

Asegúrese de que los comentarios estén sangrados al mismo nivel que el código que describen. Cuando no lo son, pueden ser difíciles de seguir.

Por ejemplo, este comentario no está sangrado o colocado correctamente:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

Se puede reescribir de la siguiente manera:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

Resumen

Los comentarios son un componente importante para escribir código comprensible. La inversión que hace al escribir un comentario es algo que su futuro yo, u otros desarrolladores que necesiten trabajar en su base de código, apreciarán. Comentar también le permite obtener información más profunda sobre su código.

En este tutorial, aprendió más sobre los comentarios en Python, incluidos los distintos tipos de comentarios de Python, cuándo usar cada uno de ellos y las mejores prácticas a seguir al crearlos.

Escribir buenos comentarios es una habilidad que necesita ser estudiada y desarrollada. Para practicar la escritura de comentarios, considere regresar y agregar comentarios a algunos de sus proyectos anteriores. Para inspirarse y ver las mejores prácticas en acción, consulte los proyectos de Python bien documentados en GitHub.

Cuando esté listo para poner en marcha sus propios proyectos de Python, la plataforma de alojamiento de aplicaciones de Kinsta puede llevar su código de GitHub a la nube en segundos.