En este capítulo, aprenderemos la gran importancia de comentar nuestro código, su importancia y algunas recomendaciones para hacerlo bien. Además, aprenderemos a crear documentación para nuestro código.
Un comentario es una línea de código que no se ejecuta. ¿Porqué no se ejecuta?, bueno Ahora que estamos haciendo unas líneas de código puede ser que no tenga mucha importancia, pero cuando empecemos a crear un proyecto más complejo o estés trabajando con un equipo, veremos los hábitos de escribir cada uno, y estos comentarios nos ayudarán a entender mejor lo que trataron de hacer en ese momento.
Incluso, cuando revises algún proyecto personal pasado que hace tiempo lo tenías guardado, te ayudará a saber qué fue lo que hiciste y no digas “Cuando escribí el código, Dios y yo sabíamos que estaba haciendo, ahora sólo Dios lo sabe”.
¿Cómo añadimos comentarios?
Para agregar un comentario sólo escribimos doble slash (//) y luego dejamos que nuestra imaginación trabaje. Apliquemos un ejemplo con la constante maximumNumberOfLoginAttempts de un capítulo anterior.
¿Y si queremos varias líneas?
Bueno, si queremos hacer varias líneas sólo vasta con colocar nuestros párrafos entre /* al inicio y */ al final. Aplicaremos un ejemplo con la variable currentLoginAttempt
¿Para qué nos puede servir comentar en Swift y Xcode?
Hasta hace poco me puse a pensar si tenía una funcionalidad adicional esto de comentar y que leamos nuestras líneas, y encontré algo muy valioso que sé que algunos ya saben: Documentar.
Creando documentación
¿Cómo veo la documentación?
Cuando queremos ver la documentación (también denominada Quick Help o Ayuda Rápida) de alguna variable, función, clase (lo veremos más adelante) u otro componente dentro de un proyecto, lo que tenemos que hacer es mantener presionada la tecla alt y hacer clic en el elemento que queremos ver su documentación.
Haremos un ejemplo con nuestra constante maximumNumberOfLoginAttempts
Podemos ver que nos muestra la declaración y dónde se encuentra declarada nuestra constante.
¿Cómo creo mi propia documentación?
Para poder crear una documentación propia y personalizada, tenemos la forma de que sea una línea o varias líneas (multilínea o párrafo).
Documentando con una sola línea
En este caso, para poder crear nuestra propia documentación, es similar a escribir un comentario, pero en esta ocasión escribiremos al inicio tres slash (///). Como ejemplo, crearemos una documentación sencilla para la constante maximumNumberOfLoginAttempts.
Nota: Toda la información de la documentación que escribiremos tiene que encontrarse arriba del elemento que se documentará.
Al escribir con tres slash (///), vemos que el formato del comentario ha cambiado, pero al igual que antes, no se ejecutará. Pero al ver la documentación (alt + clic en la constante), vemos que aparece el comentario como resumen (Summary) de nuestra constante. Acabamos de aprender a documentar nuestro código.
Documentando con muchas líneas
Para realizar una documentación un poco más extensa de nuestro código y que sea multilínea, escribimos nuestro párrafo entre /** y /*, similar a como si estuviéramos comentando. Como ejemplo, crearemos la documentación para la variable currentLoginAttempt.
Como vemos, el formato también ha cambiado, tampoco se ejecutará. Si vemos la documentación (alt + clic en la variable), notaremos que se encuentra todo nuestro contenido, pero además, hay unos detalles adicionales, como viñetas. Esto se debe a que Apple ha decidido trabajar con un estándar de documentación denominado Markdown (https://es.wikipedia.org/wiki/Markdown).
Modificando un poco el ejercicio anterior, cambiaremos los estilos de la documentación para que vean su utilidad.
El resultado final es el siguiente:
¡Listo!
Hemos aprendido:
- Comentar el código en una o varias líneas.
- Cómo ver la documentación (Quick Help) de los elementos de mi proyecto.
- Documentar mi proyecto.
- Darle un estilo a la documentación de mi proyecto.
En el siguiente capítulo aprenderemos el Tipo de Dato entero en Swift.
Si tienes consultas dudas o recomendaciones, déjalas en los comentarios.
¡Recuerda compartir el conocimiento!
Gracias por la información