Los comentarios son notas que los programadores añaden a su código para explicar lo que 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 gestionar proyectos de software.
Los comentarios ayudan a explicar tu código Python a otros programadores y pueden recordarte por qué tomaste las decisiones que tomaste. Los comentarios facilitan la depuración y revisión del código, ya que ayudan a los futuros programadores a comprender las opciones de diseño del software.
Aunque los comentarios están principalmente destinados a los desarrolladores, escribir unos comentarios eficaces también puede ayudar a elaborar una excelente documentación para los usuarios de tu código. Con la ayuda de generadores de documentos como Sphinx para proyectos Python, los comentarios en tu código pueden proporcionar contenido para tu documentación.
Echemos un vistazo al funcionamiento de los comentarios en Python.
Comentarios en Python
Según la Guía de Estilo Python PEP 8, hay varias cosas que debes tener en cuenta al escribir comentarios:
- Los comentarios deben ser siempre frases completas y concisas.
- Es mejor no hacer comentarios a que sean difíciles de entender o inexactos.
- Los comentarios deben actualizarse regularmente para reflejar los cambios en tu código.
- Demasiados comentarios pueden distraer y reducir la calidad del código. Los comentarios no son necesarios cuando el propósito del código es obvio.
En Python, una línea se declara comentario cuando comienza con el símbolo #. Cuando el intérprete de Python encuentra # en tu código, ignora todo lo que hay después de ese símbolo y no produce ningún error. Hay dos formas de declarar comentarios de una sola línea: comentarios inline y comentarios de bloque.
Comentarios Inline
Los comentarios inline proporcionan descripciones breves de variables y operaciones sencillas, y se escriben en la misma línea que la sentencia del código:
border = x + 10 # Make offset of 10pxEl comentario explica la función del código en la misma declaración que el código.
Comentarios Block
Los comentarios block se utilizan para describir la lógica compleja del código. Los comentarios block en Python se construyen de forma similar a los comentarios inline, la única diferencia es que los comentarios block se escriben en una línea aparte:
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)Ten en cuenta que cuando se utilizan comentarios block, los comentarios se escriben por encima del código que están explicando. La Guía de Estilo Python PEP8 dicta que una línea de código no debe contener más de setenta y nueve caracteres, y los comentarios inline a menudo sobrepasan esta longitud. Por eso los comentarios block se escriben para describir el código en líneas separadas.
Comentarios Multilínea
Python no admite de forma nativa los comentarios multilínea, lo que significa que no hay ninguna disposición especial para definirlos. A pesar de ello, a menudo se utilizan comentarios que abarcan varias líneas.
Puedes crear un comentario multilínea a partir de varios comentarios de una sola línea precediendo cada línea con #:
# interpreter
# ignores
# these linesTambién puedes utilizar la sintaxis de cadenas multilínea. En Python, puedes definir cadenas de varias líneas encerrándolas entre """, comillas dobles triples, o ''', comillas simples triples:
print("Multi-Line Comment")
"""
This
String is
Multi line
"""En el código anterior, la cadena multilínea no se asigna 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. La ejecución del código anterior produce la siguiente salida:
Multi-Line CommentComentarios Especiales
Además de hacer que tu código sea legible, los comentarios también sirven para algunos propósitos especiales en Python, como planificar futuras adiciones de código y generar documentación.
Comentarios Docstring de Python
En Python, los docstrings son comentarios de varias líneas que explican cómo utilizar una determinada función o clase. La documentación de tu código mejora con la creación de docstrings de alta calidad. Mientras trabajas con una función o clase y utilizas la función incorporada help(obj), los docstrings pueden ser útiles para dar una visión general del objeto.
Python PEP 257 proporciona un método estándar para declarar docstrings 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 pEn el código anterior, la docstring proporcionaba detalles sobre cómo funciona la función asociada. Con generadores de documentación como Sphinx, esta docstring puede utilizarse para dar a los usuarios de tu proyecto una visión general de cómo utilizar este método.
También se puede devolver una docstring definida justo debajo de la firma de la función o clase utilizando la función incorporada help(). La función help() toma como argumento el nombre de un objeto o función, y devuelve como salida las docstrings de la función. En el ejemplo anterior, se puede llamar a help(get_person) para mostrar los docstrings asociados a la función get_person. Si ejecutas el código anterior en un intérprete de comandos interactivo utilizando la bandera -i, podrás ver cómo Python analiza esta cadena de documentos. Ejecuta el código anterior escribiendo python -i file.py.
La llamada a la función help(get_person) devuelve un docstring para tu función. La salida contiene get_person(name, age, d=False), que es una firma de función que Python añade automáticamente.
El atributo get_person.__ doc__ también puede utilizarse para recuperar y modificar docstrings mediante programación. Después de añadir «Algo más de información nueva» en el ejemplo anterior, aparece en la segunda llamada a help(get_person). Aún así, es poco probable que necesites modificar dinámicamente los docstrings en tiempo de ejecución de esta forma.
Comentarios TODO
Al escribir código, hay ocasiones en las que debes resaltar ciertas líneas o bloques enteros para mejorarlos. Estas tareas se marcan con comentarios TODO. Los comentarios TODO resultan útiles cuando planeas actualizaciones o cambios en tu código, o si deseas informar a los usuarios o colaboradores del proyecto de que quedan por escribir secciones específicas del código del archivo.
Los comentarios TODO no deben escribirse como pseudocódigo: sólo tienen que explicar brevemente la función del código aún no escrito.
Los comentarios TODO y los comentarios block de una sola línea son muy similares, y la única diferencia 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 userEs importante señalar que, aunque muchos IDE pueden resaltar estos comentarios para el programador, el intérprete de Python no ve los comentarios TODO de forma diferente a los comentarios block.
Buenas Prácticas al Escribir Comentarios en Python
Hay una serie de buenas prácticas que se deben seguir al escribir comentarios para garantizar su fiabilidad y calidad. A continuación encontrarás algunos consejos para escribir comentarios de alta calidad en Python.
Evita lo Obvio
Los comentarios que afirman lo obvio no añaden ningún valor a tu código, y deben evitarse. Por ejemplo
x = x + 4 # increase x by 4Ese comentario no es útil, ya que simplemente afirma lo que hace el código sin explicar por qué hay que hacerlo. Los comentarios deben explicar el «por qué» más que el «qué» del código que describen.
Reescrito de forma más útil, el ejemplo anterior podría tener este aspecto:
x = x + 4 # increase the border widthLos Comentarios de Python deben ser Breves y Fáciles de Entender
Los comentarios deben ser breves y fáciles de entender. Deben estar escritos en prosa estándar, no en pseudocódigo, y deben sustituir la necesidad de leer el código real para obtener una visión general de lo que hace. Demasiados detalles o comentarios complejos no facilitan el trabajo del 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 central, los comentarios deben proporcionar un resumen general del código. Este comentario puede reescribirse como
# return area of cylinder
def get_area(r,h):
return (2*3.14*r*h) + (2*3.14*r*r)Utiliza los Identificadores con Cuidado
Los identificadores deben utilizarse con cuidado en los comentarios. Cambiar los nombres o los casos de los identificadores 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 puede reescribirse como
# return cls() after modifying arg
def func(cls, arg):
return cls(arg+5)DRY y WET
Cuando escribes código, debes adherirte al principio DRY (no repetirte) y evitar WET (escribir todo dos veces).
Esto también es válido para los comentarios. Evita utilizar varias sentencias para describir tu código, e intenta fusionar comentarios que expliquen el mismo código en un único comentario. Sin embargo, es importante que tengas cuidado al fusionar comentarios: la fusión descuidada de varios comentarios puede dar lugar a un comentario enorme que infrinja las guías de estilo y sea 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 están innecesariamente fragmentados, y pueden fusionarse en un único 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 Coherente
Asegúrate de que los comentarios tienen la misma sangría que el código que describen. De lo contrario, puede resultar difícil seguirlos.
Por ejemplo, este comentario no tiene la sangría ni la posición adecuadas:
for i in range(2,20, 2):
# only even numbers
if verify(i):
# i should be verified by verify()
perform(x)Puede reescribirse como sigue:
# 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 haces al escribir un comentario es algo que tu futuro yo — u otros desarrolladores que necesiten trabajar en tu base de código — agradecerán. Comentar también te permite obtener una visión más profunda de tu código.
En este tutorial, has aprendido más sobre los comentarios en Python, incluidos los distintos tipos de comentarios en Python, cuándo utilizar cada uno de ellos y las mejores prácticas a seguir al crearlos.
Escribir buenos comentarios es una habilidad que hay que estudiar y desarrollar. Para practicar la escritura de comentarios, considera la posibilidad de volver atrás y añadir comentarios a algunos de tus proyectos anteriores. Para inspirarte y ver las mejores prácticas en acción, consulta proyectos Python bien documentados en GitHub.
Cuando estés listo para poner en marcha tus propios proyectos Python, la plataforma de Alojamiento de Aplicaciones de Kinsta puede llevar tu código de GitHub a la nube en cuestión de segundos.
Vivek is a Python and Django developer who's always ready to learn and teach new things to fellow developers.
Deja una respuesta