in

El arte de escribir comentarios de código eficientes

El arte de escribir comentarios de código eficientes

Mejores prácticas de comentarios de código para tareas de ciencia de datos

Elena Kosourova

23 de abr·8 min de lectura

De Unsplash

Si corremos import this en un cuaderno de Jupyter, o simplemente abra este enlace, obtendremos El Zen de Python, a colección de 19 pautas para el diseño de Python recopiladas por Tim Peters. Uno de ellos dice: «La legibilidad cuenta», y en este artículo vamos a discutir exactamente uno de los aspectos de este principio: los comentarios de código, que son fragmentos de texto en lenguaje natural incluidos en el código y utilizados para su documentación. De hecho, los comentarios de código, junto con un código limpio, la denominación correcta de variables y funciones, y hacer que el código sea lo más explícito posible, contribuyen significativamente a la legibilidad de nuestros proyectos. Esto puede ser muy útil no solo para las personas que leerán nuestro trabajo en el futuro, sino también para nosotros cuando volvamos a él después de algún tiempo.

En este artículo, nos centraremos en las mejores prácticas para comentar el código Python aplicado a las tareas de ciencia de datos. Sin embargo, la mayoría de estas pautas también son válidas para cualquier otro lenguaje o esfera de programación.

Sintaxis y estilo

En Python, hay 2 tipos de comentarios de código: bloques e integrados.

Según PEP 8, bloquear comentarios empezar con un hash#) seguido de un solo espacio y constan de una o más oraciones, con la primera palabra en mayúscula y un punto al final de cada oración. Si hay varias oraciones, están separadas por dos espacios. Los comentarios de bloque están separados del código anterior por una línea vacía. Se aplican al código que les sigue directamente (sin línea vacía) y tienen la misma sangría.

Una línea larga de un comentario de bloque debe extenderse a lo largo de varias líneas, cada una de las cuales comienza con un hash seguido de un solo espacio. Otra forma de escribir comentarios de varias líneas en Python es usando cadenas de varias líneas – los incluidos en comillas triples simples o dobles. Técnicamente, fueron diseñados originalmente para otro propósito: asignar documentación a funciones, métodos o clases. Sin embargo, si no se usa con esta calidad o no se asigna a una variable, una cadena de varias líneas no genera código, por lo que puede servir como una forma poco convencional de comentar el código en Python. Este enfoque fue aprobado por el fundador de Python Guido van Rossum en su Gorjeo.

✔️
# Isolate the outliers with at least $3,500 spent per month except
# for the cases when the respondent hadn't attended any bootcamp or
# had been learning programming for a maximum 3 months before the
# survey.
above_3500 = usa[(usa['MoneyPerMonth']>=3500)
&(usa['AttendedBootcamp']!=0.0)
&(usa['MonthsProgramming']>3.0)]
✔️
'''Isolate the outliers with at least $3,500 spent per month except for the cases when the respondent hadn't attended any bootcamp or had been learning programming for a maximum 3 months before the survey.
'''
above_3500 = usa[(usa['MoneyPerMonth']>=3500)
&(usa['AttendedBootcamp']!=0.0)
&(usa['MonthsProgramming']>3.0)]
✔️
"""Isolate the outliers with at least $3,500 spent per month except for the cases when the respondent hadn't attended any bootcamp or had been learning programming for a maximum 3 months before the survey.
"""
above_3500 = usa[(usa['MoneyPerMonth']>=3500)
&(usa['AttendedBootcamp']!=0.0)
&(usa['MonthsProgramming']>3.0)]

Un comentario en línea se coloca en la misma línea que el fragmento de código que comenta, separado de él por al menos dos espacios, un hash y un solo espacio. Los comentarios en línea suelen ser más cortos y deben usarse con precaución, ya que tienden a mezclarse visualmente con las líneas de código arriba y abajo y, como consecuencia, se vuelven ilegibles, como en este fragmento de código:


ax.set_title('Book Rating Comparison', fontsize=20)
ax.set_xlabel(None) # remove x label
ax.tick_params(axis='both', labelsize=15)
plt.show()

A veces, sin embargo, los comentarios en línea pueden ser indispensables:

✔️
colors = [[213/255,94/255,0], # vermillion
[86/255,180/255,233/255], # sky blue
[230/255,159/255,0], # orange
[204/255,121/255,167/255]] # reddish purple

Preste atención a que en el código anterior, la alineación de los comentarios en línea ayuda a mejorar su legibilidad.

Aunque las pautas sobre la sintaxis de comentarios de código están diseñadas para hacer que el código sea más legible y consistente, debemos tener en cuenta que el lenguaje en sí evoluciona, y también lo hacen las convenciones de estilo. Además, una empresa (o un proyecto en particular) puede tener sus propios enfoques de estilo de codificación, y luego se da prioridad a esas recomendaciones específicas para cada caso, si son diferentes de PEP 8. Por lo tanto, a veces se pueden ignorar las pautas oficiales. Sin embargo, algunas prácticas deben evitarse casi siempre:

  • Usar más de un hash antes de un comentario
  • Usar uno o más hash también al final de un comentario
  • Omitir un espacio entre un hash y un comentario
  • Usando todas las letras mayúsculas (veremos más adelante una excepción)
  • Omitir una línea vacía después de un fragmento de código encima del comentario
  • Insertar una línea vacía entre un comentario y su código relacionado
  • Ignorando la sangría del código comentado

Estos enfoques no son deseables porque abarrotan el código con elementos innecesarios, disminuyen su legibilidad y dificultan la distinción entre bloques de código separados. Compare estas piezas idénticas de código de manera diferente en el estilo de los comentarios:


###REMOVE ALL THE ENTRIES RELATED TO 2021###
questions = questions[questions['Date'].dt.year < 2021]
###CREATE A LIST OF TAGS###
tags_list = list(tags.keys())✔️
# Remove all the entries related to 2021.
questions = questions[questions['Date'].dt.year < 2021]
# Create a list of tags.
tags_list = list(tags.keys())

Escribir comentarios significativos

Si el código en sí dice qué hacer con una computadora, los comentarios del código se dirigen a los seres humanos, explicándoles qué hace exactamente este código y especialmente por qué lo necesitamos. Sobre el “qué”, existe una opinión generalizada de que si nuestro código es lo más explícito y sencillo posible, si usamos nombres autoexplicativos para variables y funciones, entonces casi no necesitamos comentarios de código en absoluto. Aunque estoy de acuerdo en que escribir un código fácilmente comprensible y seleccionar cuidadosamente los nombres de las variables / funciones es muy importante, diría que los comentarios de código también son bastante útiles.

  • Ayudan a dividir el código en varias partes lógicas, lo que facilita la navegación.
  • Son útiles para explicar la funcionalidad de un método / función nuevo o poco utilizado. Además, es una buena idea agregar comentarios de código si tenemos que aplicar un enfoque inusual / no evidente a la codificación debido a que tal vez se detecten algunos errores / problemas técnicos / conflictos de versión al intentar seguir un camino más explícito.
  • Al escribir un código, debemos tener en cuenta a las personas (por ejemplo, nuestros colegas) que podrían leer nuestro código en el futuro. Lo que está claro para una persona puede no serlo en absoluto para otra. Por lo tanto, debemos tratar de tener en cuenta una posible brecha en la experiencia, el conocimiento técnico y contextual de diferentes personas, y facilitar su tarea mediante el uso de comentarios.
  • Los comentarios del código son valiosos para agregar información sobre los autores, una fecha y el estado de las modificaciones (p. Ej. # Updated by Elena Kosourova, 22.04.2021. Added an annotation of the current year on the graph.).

Por lo tanto, comentar el código es un enfoque rápido y poderoso para mejorar la legibilidad y la accesibilidad del código, y para escribir comentarios claros y significativos, no es suficiente ser un buen codificador; también es importante ser un buen escritor, que es casi una habilidad para aprender per se.

Consideremos algunas sugerencias que debemos seguir para aplicar los comentarios de código de manera eficiente y evitar su uso excesivo.

Evite los comentarios de código obvios

Nuestros comentarios no deben indicar cosas evidentes o claras a partir del contexto. Una vez más, recordemos aquí que lo «evidente» puede variar de una persona a otra, y también es importante el alcance y la audiencia objetivo de nuestro trabajo (por ejemplo, si estamos escribiendo un proyecto de datos reales sobre ciencia de datos o un manual para estudiantes). Nuestra tarea aquí es encontrar el equilibrio.


# Import libraries.
import pandas as pd
import numpy as np

Evite comentarios de código ineficientes

Para ser útiles al máximo, nuestros comentarios de código deben ser tan precisos y lacónicos como sea posible, dando todos los detalles necesarios sobre su código y excluyendo cualquier información irrelevante como observaciones del código anterior, intenciones para el futuro o paréntesis. Además, dado que el código suele implicar cierta dinámica (es lo hace, crea, elimina, etc.), una buena práctica es utilizar verbos en lugar de sustantivos:

Too vague
# Select a specific type of columns.
characters = star_wars.iloc[:, 15:29]
Too wordy
# Now, let's select all the columns of a radio-button type from our dataframe.
characters = star_wars.iloc[:, 15:29]
Observations from the previous code
# Select radio-button type columns, as done earlier for checkbox type ones.
characters = star_wars.iloc[:, 15:29]
Using a noun instead of a verb
# Selection of radio-button type columns.
characters = star_wars.iloc[:, 15:29]
✔️ Good
# Select radio-button type columns.
characters = star_wars.iloc[:, 15:29]

Actualizar comentarios de código

Es un error complicado y muy común, pero siempre debemos recordar introducir todas las modificaciones necesarias también en los comentarios del código cuando el código cambia. Como dice PEP 8, “clos comentarios que contradicen el código son peores que ningún comentario ”. Es más, a veces tenemos que comprobar no solo el comentario del código relacionado con el fragmento de código modificado, sino también los demás que pueden verse indirectamente influenciados por dichos cambios.

Idioma a utilizar

Una práctica común es escribir los comentarios de código siempre en inglés. Sin embargo, esta es una de esas reglas que se pueden ignorar en algunos casos: si estamos absolutamente seguros de que nuestro código nunca será leído por personas que no hablen nuestro idioma (o cualquier otro idioma en común), entonces ‘ Será mejor que escriba los comentarios exactamente en ese idioma. En este caso, el código se vuelve más comprensible exactamente para nuestro público objetivo en particular.

Comentar fragmentos de código

A veces, trabajando en un proyecto, nos resulta útil probar varios métodos para la misma tarea o para depurar el código, y luego podemos decidir mantener algunas de esas piezas probadas comentadas, incluso si seleccionamos otro al final , por si acaso. Sin embargo, este enfoque es bueno solo temporalmente, y en la versión final del proyecto, es importante limpiar esos fragmentos. De hecho, puede ser una gran distracción para aquellas personas (incluyéndonos a nosotros después de un tiempo) que leerán este código en el futuro. El lector podría comenzar a tener dudas sobre si el fragmento de código comentado fue de alguna manera útil en algún paso y si debería mantenerse en el proyecto. Para evitar esta confusión, es mejor eliminar todo el código comentado.

Como es habitual, puede haber excepciones muy raras a esta práctica recomendada. Digamos que nuestro trabajo consiste en mostrar diferentes formas de obtener el mismo resultado, y un enfoque es más preferible a otro (que aún es factible pero menos utilizado). En este caso, podemos centrarnos en el enfoque principal y mostrar el segundo como un código comentado, con un comentario correspondiente. Además, aquí podemos hacer otra excepción mencionada anteriormente y usar letras mayúsculas para el comentario del código, para hacerlo un poco más visible:

✔️
# Create a stem plot.
plt.stem(months.index, months)
# # ALTERNATIVE WAY TO CREATE A STEM PLOT.
# plt.vlines(x=months.index, ymin=0, ymax=months)
# plt.plot(months.index, months, 'o')

Conclusión

Con todo, código comentando …

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Notificacion de mensajes

¿Cómo veo el historial de notificaciones de mi Android o iPhone?

1632804049 social og oracle badge

Análisis de registro | Oráculo