Si pasa una cantidad razonable de tiempo programando, seguramente encontrará comentarios de código. Es posible que incluso hayas escrito algunos tú mismo. Estos pequeños fragmentos de texto están incrustados en el programa, pero el compilador o el intérprete los ignoran. Están destinados a los humanos que trabajan con el código y tienen muchas aplicaciones. Incluso pueden remodelar su código o crear documentación para otros automáticamente. ¿Quieres saber cómo usarlos correctamente? ¡Entonces estás en el lugar correcto!

Es hora de explorar los comentarios, cómo usarlos y también cómo no para usarlos.

Lo que aprenderás:
Al leer este artículo, aprenderá:

• Qué es un comentario, tipos y cómo usarlos.
• Dónde empezaron y dónde están ahora.
• La diferencia entre buenos y malos comentarios.
• Aplicaciones prácticas del pasado y del presente.

Al final del artículo, sabrá por qué los comentarios de código son importantes, las mejores prácticas para escribir comentarios efectivos, algunas trampas y errores comunes que se deben evitar y las herramientas y recursos que puede usar para optimizar su proceso de comentarios de código, incluidos los generadores de documentación automatizados. , linters de comentarios y plataformas de revisión de código.

Comenzará con una mirada en profundidad a lo que son los comentarios de código.

¿Qué son los comentarios de código?

Comentarios dentro de un programa de software hay anotaciones legibles por humanos que los programadores agregan para proporcionar información sobre lo que está haciendo el código. Los comentarios toman muchas formas, según el lenguaje de programación y la intención del comentario.

Se clasifican en dos tipos: comentarios de bloque y comentarios de línea.

• Bloquear comentarios delimite una región dentro del código utilizando una secuencia de caracteres al comienzo del comentario y otra secuencia de caracteres al final. Por ejemplo, algunos usan /* al principio y */ al final.
• Comentarios de línea use una secuencia de caracteres para pedirle al compilador que ignore todo, desde el comienzo del comentario hasta el final de la línea. Por ejemplo: #, – or //. La forma de indicar los comentarios de línea depende del lenguaje de programación que esté utilizando.

Aquí hay un ejemplo de cómo se ve cada tipo de comentario en Swift:

struct EventList: View { // ESTE ES UN COMENTARIO DE LÍNEA @EnvironmentObject var userData: UserData @EnvironmentObject var eventData: EventData /* ESTE ES UN COMENTARIO DE BLOQUE @State private var isAddingNewEvent = false @State private var newEvent = Event() */ var cuerpo: algunos Ver { ... } }

Algunos lenguajes de programación solo admiten un tipo de secuencia de comentarios y algunos requieren soluciones alternativas para que una secuencia funcione. Así es como algunos idiomas manejan los comentarios:

Piensa en cómo usarías una nota adhesiva. Para los programadores, un comentario es una nota adhesiva con usos ilimitados.

Los comentarios han adquirido más importancia con el tiempo a medida que sus usos se han ampliado y estandarizado. Aprenderá sobre muchos de estos usos en este artículo.

Una breve historia del comentario

No hace mucho tiempo, las computadoras no se programaban usando una pantalla y un teclado. Fueron programados usando tarjetas perforadas: pequeños pedazos de papel rígido con agujeros perforados en una secuencia para indicar instrucciones para una computadora. Estos se convertirían en pilas gigantes que se introducirían en un lector y la computadora ejecutaría el programa.

Era difícil saber de un vistazo qué hacía cada carta o conjunto de cartas. Para resolver esto, los programadores escribirían notas sobre ellos. Estas notas fueron ignoradas por el lector de la máquina porque solo leyó los agujeros en la tarjeta. Aquí hay un ejemplo:

Hoy en día, la mayoría de los comentarios tienen el mismo propósito: ayudar a comprender qué hace el código.

Código sin comentarios

Un dicho común entre los programadores es: "El buen código no necesita una explicación". Esto es cierto hasta cierto punto, y algunos programadores no escriben comentarios en su código.

Pero, ¿qué sucede cuando ese código se vuelve realmente grande? ¿O incorpora varias reglas de negocio y lógica? ¿U otras personas necesitan usarlo? Sería posible descifrar el código no comentado, pero ¿a qué costo en tiempo y esfuerzo?

Cuando nuestro enfoque está constantemente en escribir código, olvidamos que unos meses, incluso algunas semanas, después de escribir dicho código, gran parte de la lógica se ha ido de nuestra memoria. ¿Por qué tomamos ciertas decisiones? ¿Por qué usamos ciertas convenciones? Sin comentarios, tendremos que pasar por el costoso ejercicio de averiguar lo que estábamos pensando.

Los comentarios son increíblemente útiles y los buenos desarrolladores deberían usarlos. Sin embargo, todos los comentarios no son iguales. He aquí un vistazo a lo que hace que los comentarios sean buenos, inútiles o incluso contraproducentes.

Buenos comentarios

Los buenos comentarios son simples y fáciles de leer. Aclaran o indican una línea de pensamiento en lugar de cómo funciona el código.

Toman muchas formas, como anotaciones, enlaces y citas de fuentes, licencias, banderas, tareas, comandos, documentación, etc.

Comentarios inútiles

Los comentarios son buenos, pero no es necesario usarlos. en todas partes. Una trampa común es usar comentarios para describir qué está haciendo el código, cuando eso ya está claro.

Por ejemplo, si tiene un código que itera a través de una matriz e incrementa cada valor, no hay necesidad de explicarlo; debería ser obvio para el programador que está revisando el código. Qué no va obvio, sin embargo, es porque estás haciendo eso Y eso es lo que un buen comentario explicará.

Describir lo obvio es una trampa común... y los comentarios que hacen esto solo ocupan espacio y pueden causar confusión.

malos comentarios

Los malos comentarios son más destructivos que inútiles. Causan confusión, o peor aún, intentan excusar un código enrevesado o mal escrito. No intente utilizar los comentarios como sustituto de un buen código. Por ejemplo:

var n = 0 // Número de línea

En su lugar, haz lo siguiente:

var número de línea = 0

Abusar de los comentarios, como saturar el código con comentarios TODO, BUG y FIXME, es una mala práctica. La mejor solución es resolverlos antes de confirmar el código cuando se trabaja en equipo, o simplemente crear un problema en un sistema de emisión de tickets.

Dado que los comentarios son de forma libre, es útil tener algunas convenciones o plantillas para determinar cómo debe verse un comentario, pero mezclar convenciones cae en la categoría de malos comentarios.

¿Comentaste el código durante el desarrollo? No lo cometa: resuelva el problema y elimine el comentario antes de que confunda a otros en el equipo.

Más allá de las anotaciones

Hasta este momento, ha aprendido a utilizar los comentarios como anotaciones. Sin embargo, dado que los comentarios no tienen un formato predefinido, puede extender su uso transformando su humilde anotación de comentario en un archivo de datos o documento especializado. Aquí hay algunos buenos ejemplos.

LICENCIA Comentarios

LICENCIA es un tipo de comentario que indica términos y condiciones para el código. Los verá especialmente a menudo en código fuente abierto. Aquí hay un ejemplo de la LICENCIA MIT:

/* EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO VIOLACIÓN. EN NINGÚN CASO LOS AUTORES O LOS TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMACIÓN, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO TIPO, QUE SURJA DE, FUERA DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE. */

Dado que los comentarios son de forma libre, la forma en que se escribe el comentario puede tomar muchas formas. Aquí hay un ejemplo de Apple:

//===------------------------------------------------------------ ------------------===// // // Este archivo fuente es parte del proyecto de código abierto de Swift // // Copyright (c) 2015-2016 Apple Inc. y los autores del proyecto Swift // Con licencia Apache License v2.0 con Runtime Library Exception // // Consulte http://swift.org/LICENSE.txt para obtener información sobre la licencia // Consulte http://swift.org/ CONTRIBUTORS.txt para la lista de autores de proyectos Swift // //===--------------------------------- ------------------------------===//

CODIGO DE SALIDA TEMPORAL Comentarios

Los programadores usan el CÓDIGO DE SALIDA TEMPORAL comentario como una herramienta para la depuración. Al sacar un bloque o una línea de código del proceso de compilación, puede modificar qué código se ejecuta y cuál no. Este método se usa comúnmente cuando se realiza una depuración de proceso de eliminación. Por ejemplo (solo compilación para iOS):

let paquete = Paquete( nombre: "CommentOut", plataformas: [ .iOS(.v14), /* .tvOS(.v14), .watchOS(.v7), .macOS(.v11) */ ], productos: [ .library(name: "CommentOut", objetivos: ["CommentOut"]) ], targets: [ .target(name: "CommentOut") ] )

Comentarios DECORATIVOS

A DECORATIVO or SEPARADOR comentario puede separar un archivo o bloques de código por alguna categoría o función. Esto ayuda a los usuarios a encontrar el código más fácilmente. Aquí hay un ejemplo:

/**************************************************** * * Ayudantes de implementación de Huffman * ******************************************** ******/

Comentarios LÓGICOS

LÓGICA los comentarios documentan la lógica que eligió al crear el código. Esto va más allá de lo que muestra el código, como "¿Cuál fue ese valor asignado?"

Por ejemplo (de swift-package-manager/Fuentes/Comandos/SwiftRunTool.swift, líneas 287-288):

private func execute(ruta: String, args: [String]) throws -> Never { #if !os(Windows) // En plataformas que no sean Windows, Signal(SIGINT, SIG_IGN) se usa para manejar SIGINT por DispatchSourceSignal, // pero este proceso está a punto de ser reemplazado por exec, por lo que SIG_IGN debe volver a su valor predeterminado. señal (SIGINT, SIG_DFL) #endif intente TSCBasic.exec (ruta: ruta, args: args) }

En este caso, el execute La función contiene instrucciones condicionales de compilación que incluirán u omitirán la llamada de señal. El comentario contiene la explicación de por qué hace esto.

Formas Avanzadas de Comentarios

Los comentarios pueden contener contenido especializado, típicamente formateado como lo sería un archivo de datos: un archivo dentro del código. También pueden ser indicadores simples, a los que las herramientas de análisis de código fuente pueden responder de diferentes maneras.

Marcar comentarios

Destacar los linters suelen utilizar los comentarios; habilitan o deshabilitan funciones. Así es como SwiftLint deshabilita funciones usando comentarios de bandera:

struct GitHubUserInfo: Content { let nombre: String // swiftlint: deshabilitar nombre_identificador let avatar_url: ¿String? // swiftlint: habilitar nombre_identificador }

Los propios compiladores también utilizan los comentarios de marca como una forma de configuración. En el siguiente ejemplo, verá una secuencia de comandos de Python que se ejecuta como secuencia de comandos CLI y en formato UTF-8:

#!/usr/bin/env python3 # -*- codificación: UTF-8 -*-

Note: La primera línea de comentario en los scripts tiene un nombre formal: el tinglado. Su propósito es indicar qué intérprete debe usar el sistema operativo cuando ejecuta el script. Siempre comienza con un #!.

TAREA Comentarios

Los entornos de desarrollo integrados (IDE), los editores de texto y algunas herramientas CLI pueden leer TAREA comentarios dejados por los programadores en un formato que indica una acción a realizar por el programador en el futuro, como TODO:

// TODO: Cambiar permisos de modelo // FIXME: Convertir cadenas a Enum

GENERACIÓN DE DOCUMENTOS Comentarios

GENERACIÓN DE DOCUMENTOS Los comentarios permiten que una herramienta analice el código fuente y genere un documento formateado, generalmente HTML, que los usuarios finales pueden usar para buscar clases, métodos, etc. Aquí hay un ejemplo de JavaDoc:

/** * @param string la cadena a convertir * @param type el tipo para convertir la cadena a * @param el tipo del elemento * @param el valor del elemento */ V convert(String string, Clase tipo) { }

Otras herramientas pueden generar documentación que los IDE ven y se muestran al usuario dentro del código. Una de estas herramientas es Documentation Markup (DocC). Esto es particularmente útil para las API que Apple usa con sus propias bibliotecas. Aquí hay un ejemplo del proyecto SwiftGD de código abierto:

/// Exporta la imagen como objeto `Data` en formato raster especificado. /// /// - Formato de parámetro: el formato de trama de los datos de imagen de retorno (por ejemplo, como jpg, png, ...). El valor predeterminado es `.png` /// - Devuelve: los datos de la imagen /// - Lanza: `Error` si falla la exportación de `self` en el formato de trama especificado. Exportación de funciones públicas (como formato: ExportableFormat = .png) lanza -> Datos {return try format.data (of: internalImage)}

Comentarios de CDATA

CDATA Los comentarios incrustan datos formateados en archivos XML y XHTML. Puede usar varios tipos diferentes con estos comentarios, como imágenes, código, XML dentro de XML, etc.:

John Smith ]]>

Del artículo de Wikipedia sobre Comentarios de programación informática, Usted tiene el DIRECTORIO DE tipo de comentario de inclusión: "Los logotipos, diagramas y diagramas de flujo que consisten en construcciones de arte ASCII se pueden insertar en el código fuente formateado como un comentario". Por ejemplo:

ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]>

Divertirse con los comentarios

El hecho de que los comentarios no estén incluidos en una aplicación no significa que no puedas divertirte con ellos. Lecciones de vida, chistes, poesía, juegos de tres en raya y algunas bromas de compañeros de trabajo se han convertido en comentarios de código. Aquí hay un ejemplo de py_easter_egg_zen.py:

import this # The Zen of Python, de Tim Peters # Bello es mejor que feo. # Explícito es mejor que implícito. # Lo simple es mejor que lo complejo. # Complejo es mejor que complicado. # Plano es mejor que anidado. # Disperso es mejor que denso. # La legibilidad cuenta. # Los casos especiales no son lo suficientemente especiales como para romper las reglas. # Aunque la practicidad le gana a la pureza. # Los errores nunca deben pasar en silencio. # A menos que se silencie explícitamente. # Frente a la ambigüedad, rechace la tentación de adivinar. # Debe haber una, y preferiblemente solo una, forma obvia de hacerlo. # Aunque esa forma puede no ser obvia al principio a menos que seas holandés. # Ahora es mejor que nunca. # Aunque nunca suele ser mejor que *ahora* ahora. # Si la implementación es difícil de explicar, es una mala idea. # Si la implementación es fácil de explicar, puede ser una buena idea.

Importante:: Los comentarios de huevo de Pascua no son bienvenidos en todos los códigos fuente. Consulte la política del proyecto o repositorio o el manual del empleado antes de realizar cualquiera de estas acciones.

Puntos clave

Hoy aprendiste que hay más en los comentarios de lo que parece. Una vez considerados una ocurrencia tardía, ahora son reconocidos como una herramienta de comunicación invaluable para la programación.

• Ayudan a documentar y preservar el conocimiento para el futuro mantenimiento del código.
• Hay buenos comentarios y malos comentarios.
• Los comentarios pueden ayudar a crear documentación automatizada.

Ahora, ¡es hora de practicar! La única forma de ser bueno con los comentarios es participar y agregarlos.

Al hacer que los comentarios sean parte de su proceso de pensamiento de programación, ya no se convierten en un paso adicional para realizar. Aquí hay algunas maneras de practicar:

• Documente sus proyectos actuales y tenga en cuenta los estándares establecidos para el proyecto o repositorio.
• Use un linter en todos sus proyectos para mantener el formato y las convenciones bajo control.
• Encuentre un generador de documentos y publique su trabajo.

Puede practicar y contribuir mientras apoya un proyecto de código abierto que necesita ayuda con comentarios y documentación.

¿A dónde ir desde aquí?

Si desea obtener más información sobre cómo comentar, consulte estos artículos y recursos. Muchos de ellos fueron consultados en la redacción de este artículo.

¡Esperamos que hayas disfrutado este vistazo a los comentarios! ¿Tiene preguntas, sugerencias o consejos para compartir? Únase a nosotros en el foro para este artículo. Todos pueden aprender unos de otros.

Sobre la autora

Roberto Machorro ha estado programando profesionalmente durante más de 25 años y comentando código durante el mismo tiempo. Ha defendido la documentación de código interno, de terceros y de fuente abierta debido a la frustración de tener que mantener un código mal escrito o luchar con la documentación no disponible. Comenzó con los documentos de la biblioteca usando HeaderDoc, JavaDoc y ahora disfruta de DocC.

• Distribución de relaciones públicas y contenido potenciado por SEO. Consiga amplificado hoy.
• PlatoData.Network Vertical Generativo Ai. Empodérate. Accede Aquí.
• PlatoAiStream. Inteligencia Web3. Conocimiento amplificado. Accede Aquí.
• PlatoESG. Automoción / vehículos eléctricos, Carbón, tecnología limpia, Energía, Ambiente, Solar, Gestión de residuos. Accede Aquí.
• Desplazamientos de bloque. Modernización de la propiedad de compensaciones ambientales. Accede Aquí.
• Fuente: https://www.kodeco.com/38887676-code-comments-how-to-write-clean-and-maintainable-code