Comentando código
Dart, como la mayoría de los lenguajes de programación, permite documentar el código mediante comentarios. Estos permiten escribir texto directamente junto al código, sin que el compilador lo note.
La profundidad y complejidad del código que escribes pueden oscurecer los detalles generales de por qué lo escribiste de cierta manera, o incluso qué problema resuelve. Para evitarlo, es buena idea documentar lo que escribiste para que la próxima persona que revise tu código pueda comprenderlo. Después de todo, ¡esa próxima persona podría ser tu futuro!
La primera forma de escribir un comentario en Dart es iniciar una línea con dos barras diagonales:
// This is a comment. It is not executed.Este es un comentario de una sola línea.
Puede apilar comentarios de una sola línea para poder escribir comentarios de varias líneas como se muestra a continuación:
// This is also a comment,
// over multtiple lines.También puedes crear bloques de comentarios colocando el texto de tu comentario entre /* y */:
/* This is also a comment. Over many...
many...
many lines. */El inicio se denota con /* y el final se denota con */.
Dart también te permite anidar comentarios, de la siguiente manera:
/* This is a comment.
/* And inside it is
another comment */
Back to the first. */Además de estas dos formas de escribir comentarios, Dart también ofrece un tercer tipo llamado comentarios de documentación. Los comentarios de documentación de una sola línea comienzan con ///, mientras que los comentarios de documentación en bloque se encierran entre /** y */. A continuación, se muestra un ejemplo de cada uno:
/// I am a documentation comment
/// at your service.
/**
* Me, too!
*/Los comentarios de documentación son súper útiles porque puedes usarlos para generar… ¡lo adivinaste!… ¡documentación! Querrás agregar comentarios de documentación a tu código siempre que tengas una API pública para que los usuarios, y tú mismo en el futuro, sepan cómo funciona tu API. Aunque este libro no profundiza en esto, los comentarios de documentación incluso admiten el formato Markdown, lo que te permite agregar elementos como ejemplos de código o enlaces a tus comentarios.
La documentación de Flutter y Dart es conocida por sus comentarios detallados. Y dado que el código de Flutter y Dart es de código abierto, simplemente revisarlo es una excelente manera de aprender cómo se escriben los buenos comentarios de la documentación.
De hecho, puedes intentar consultar esa documentación ahora mismo. Toma el programa “Hola Dart” del Capítulo 1, “Hola, Dart”:
void main() {
print('Hello, Dart!');
}En VS Code, Comando+Clic en una Mac, o Control+Clic en una PC, la palabra clave print VS Code lo llevará al código fuente para esa palabra clave y verá los comentarios de la documentación para print:
/// Imprime una representación de cadena del objeto en la consola.
void print(Object? object) {Hablando de print, esa es otra herramienta útil al escribir código Dart.
Salida de impresión
print mostrará lo que desee en DEBUG CONSOLE (la consola de depuración).
Por ejemplo, considere el siguiente código:
print('Hello, Dart Apprentice reader!');Ejecute este código y mostrará un bonito mensaje en la DEBUG CONSOLE, como el siguiente:
¡Hola, lector Aprendiz de Dart!
ExitedAñadir sentencias print a tu código es una forma sencilla de supervisar lo que sucede en un punto específico. Más adelante, cuando estés listo para llevar tu depuración al siguiente nivel, puedes consultar algunos de los paquetes de registro más detallados en https://pub.dev/.
Puedes imprimir cualquier expresión en Dart. Para saber qué es una expresión, sigue leyendo.