Escribir buenos comentarios en Python permitirá que otros desarrolladores y evaluadores lean y comprendan su código fácilmente.
El código limpio con sintaxis coherente, denominación de variables descriptivas y sangría es como el primer libro, más fácil de entender y mantener.
Además, hoy en día, es menos común que una persona escriba el código completo de toda la aplicación o software; más bien, un equipo o grupo de personas trabajará para lograr el mismo objetivo. En este caso, un código limpio y legible hace que la colaboración sea más sencilla y eficiente.
Los desarrolladores y evaluadores siempre intentan implementar software libre de errores en producción. Escribir código limpio y legible acelera este proceso al hacer que la depuración sea más sencilla y precisa. Aunque encuentre algunos errores en la producción, el código más limpio es más fácil de actualizar.
Más importante aún, el código limpio y legible dura más porque se mantiene actualizado a medida que pasa el tiempo.
Finalmente, es crucial tener un código limpio y legible para crear software duradero. Pero la pregunta es, ¿cómo logramos exactamente eso? Bueno, un método es utilizar Comentarios.
¿No es frustrante cuando has escrito todo el código para una lógica compleja, pero al día siguiente no puedes continuar donde lo dejaste? Esto no sucede cuando escribes comentarios.
Los comentarios son un lenguaje humano que explica lo que está haciendo el código fuente. Puedes escribirlos en cualquier idioma, preferiblemente inglés, ya que es un idioma global.
Entonces, cada vez que regreses a tu código fuente después de días o incluso años, los comentarios te explicarán lo que escribiste una vez.
Además, ayudan a otros desarrolladores a comprender fácilmente su código. Por eso el código escrito con comentarios permanece para siempre, incluso en ausencia de su autor.
Además, es bastante común tener conflictos al tratar con diferentes lenguajes de programación, especialmente cuando se trabaja en equipo. Ahí es donde los comentarios vienen al rescate. Aunque no conoces el lenguaje de programación del código fuente escrito por tu compañero de equipo, los comentarios te ayudan a comprender la lógica detrás de él.
La documentación del código es una forma más completa de mantener su código fuente y permite que su equipo colabore sin problemas. Contiene todo sobre el código, como el diseño, funcionalidad, arquitectura, componentes, etc.
Los comentarios incluso contribuyen a la documentación de este código. Los comentarios bien escritos se pueden incorporar directamente a la documentación del código para que los desarrolladores no sólo entiendan el qué y el por qué, sino también el cómo de su código.
- Los comentarios no solo leen el código, sino que también lo ayudan a comprender la intención del desarrollador detrás de cada línea. Entonces, si encuentra algún error en el futuro, sabrá dónde realizar exactamente las actualizaciones del código.
- Puede escribir comentarios como un párrafo para todo el código o líneas individuales que expliquen qué hace cada bloque de código. De esta manera, le permitirán a usted y a otros desarrolladores comprender bien el código, mejorando la legibilidad.
- Los comentarios pueden dividir el código en secciones lógicas, lo que simplifica la navegación por el código.
- Debe incluir comentarios que detallen las entradas, salidas y casos de uso esperados para que un evaluador pueda leer su código.
- Finalmente, incluir comentarios bien escritos en su documentación mejora la legibilidad general de la documentación del código.
Los comentarios en Python comienzan con un símbolo de almohadilla (#). Entonces, cuando comienzas una línea con hash (#), todo lo escrito en esa línea se trata como un comentario.
Cuando ejecuta el código, el compilador ignora la línea que comienza con hash (#) como si ni siquiera existiera. Sin embargo, los comentarios permanecen visibles en el código fuente para cumplir su propósito.
Hay tres tipos principales.
Estos son los que has visto arriba. Comienzan con el símbolo almohadilla (#). Básicamente, la línea que comienza con el símbolo almohadilla (#) está dedicada al comentario. Por lo tanto, esto se denomina comentario de una sola línea, donde puede escribir un comentario solo en una línea que comience con almohadilla (#).
Así es como puedes escribir comentarios de una sola línea.
# This is single line comment.
Técnicamente, Python no admite comentarios de varias líneas, pero hay formas de lograrlo en Python.
También puedes usar hash (#) para escribir comentarios de varias líneas. Cada línea que escriba debe comenzar con un símbolo de almohadilla (#).
# This is the first comment. # This is second comment. # This is the last comment.
Tabla de contenido
#3. Cadenas de documentos de Python
Una forma popular de escribir comentarios de varias líneas es utilizar cadenas literales: “””….”””. Cuando escribes algo entre comillas triples, el compilador de Python ignora esas líneas y ejecuta la parte restante del archivo.
Estos comentarios se denominan cadenas de documentos cuando se escriben justo después de las funciones, módulos y clases.
Aquí está la sintaxis para hacer esto.
""" Multi-line comments using docstrings in Python. """
Escribir comentarios claros y detallados mejora la legibilidad y el mantenimiento del código. Entonces, estas son las mejores prácticas para realizar comentarios claros en Python.
Los comentarios no deben limitarse a narrar lo que hace el código, sino que deben reflejar el propósito y la intención detrás de cada línea.
Elimine los comentarios obsoletos y asegúrese de actualizarlos cada vez que modifique el código.
En lugar de historias largas, escriba comentarios breves y concretos.
Bad example: The function takes a,b as input, calculates a + b, and returns the value. Good example: The function returns the sum of a and b.
El uso de nombres significativos y descriptivos para variables y nombres de funciones puede eliminar comentarios redundantes.
¿Código primero? ¿O comentar primero? Comentar antes de codificar es la mejor práctica; es decir, escribe tus comentarios y luego el código correspondiente. De esta manera, primero puedes pensar en la lógica y luego convertirla en código.
# Returns true if the cnt is less than 1. return cnt < 1
Utilice un formato de comentarios coherente, como espaciado, sangría, tipo de comentarios, etc., para todo el código. Esto será menos confuso y más organizado para los lectores.
Utilice cadenas de documentos para explicar funciones y clases en Python como se muestra en el siguiente ejemplo.
def add_num(a,b):
""" this function returns the sum of a and b """
sum = a+b
return sum
Evite comentarios innecesarios en su código. Por ejemplo, la siguiente línea de código no necesita ningún comentario para entenderla.
ans = 42
#1. Editor de código de Visual Studio
Editor de código de Visual Studio es el mejor IDE creado por Microsoft para un entorno de desarrollo completo. Con soporte nativo para Node.js y JavaScript, la herramienta también soporta muchos otros lenguajes de programación sin problemas.
Esta herramienta altamente personalizable tiene varias extensiones para diferentes funcionalidades. ‘Better Comments’ es una de esas extensiones que le permite crear comentarios amigables para los humanos.
Puede categorizar sus comentarios en alertas, consultas, destacados, etc., para facilitar la navegación.
El código VS admite la edición con múltiples cursores para que pueda comentar o editar varias líneas simultáneamente.
Este editor está disponible en todas las plataformas principales como Mac, Windows y Linux.
#2. Texto sublime
Texto sublime es el editor de referencia para proyectos grandes y codificación intensa. El editor es conocido por su velocidad, personalización y atajos.
La potente función de resaltado de sintaxis de la herramienta le ayuda a distinguir fácilmente entre el código y los comentarios.
Al igual que el código VS, Sublime Text también admite la edición con múltiples cursores para comentar varias líneas al mismo tiempo.
Gracias a su función de autocompletar. No es necesario repetir manualmente las líneas de código; esta función completa automáticamente su código según los patrones, lo que le ayuda a codificar más rápido.
Además, la función ‘Ir a cualquier cosa’ de la herramienta le permite cambiar entre las funciones y archivos de su proyecto sin problemas.
#3. Bloc de notas++
Panel de nodos++ es un editor de texto popular y sencillo escrito en C++ y admite numerosos lenguajes de programación. No parece un editor moderno como VS Code o Sublime Text; su interfaz es muy sencilla y parece que hace lo que necesita.
Nodepad++ ofrece numerosos atajos estándar para realizar comentarios eficientes. También puedes personalizar el teclado de acceso directo para personalizar tu experiencia de comentarios.
Su función de mapa de documentos le muestra una descripción general de la estructura del proyecto, lo que le permite navegar por los archivos, carpetas y el código sin problemas.
#4. Empuje
Empuje IDE proporciona un desarrollo y ejecución de código más rápidos. Todo y cualquier cosa se puede hacer en este editor usando atajos de teclado, por lo que debes esforzarte mucho para dominarlo.
Este editor centrado en el teclado también ofrece muchas funciones de comentarios mediante atajos de teclado. Tiene potentes funciones y comandos para navegar eficazmente por los comentarios.
Este software liviano puede manejar archivos enormes y cientos de lenguajes de programación. ¿Quién odia las cosas gratis? Como todos los editores de la lista, Vim también es completamente gratuito y de código abierto.
Viene de forma nativa en sistemas macOS y Linux y se puede descargar en Windows.
#5. PyCharm
PyCharm es un potente IDE especialmente diseñado para el desarrollo de Python. Aunque admite muchos otros lenguajes de programación, funciona mejor con Python. Tiene funciones de finalización de código, resaltado de sintaxis y depuración adaptadas a Python.
Además, hace que los comentarios en Python sean mucho más eficientes. Proporciona funciones de navegación para ayudarle a acceder fácilmente a comentarios específicos.
Obtenga varias plantillas de comentarios y cree plantillas de comentarios personalizadas de manera eficiente en Pycharm.
Además, las herramientas de refactorización del editor le permiten actualizar o corregir comentarios fácilmente.
Conclusión
Es necesario seguir los estándares de código durante todo el proceso de desarrollo de código y es obligatorio para escribir código listo para producción, ya que su código debe ser legible por todos los demás desarrolladores y evaluadores.
Una práctica importante para crear un código legible es escribir comentarios. Los comentarios están disponibles en casi todos los lenguajes de programación. Sin embargo, con este artículo, ahora debería saber cómo escribir comentarios en Python, sus tipos y las mejores prácticas a seguir al escribir comentarios.
Además, a continuación se enumeran los mejores editores de código que le ayudarán en la gestión de comentarios.