Home » Guías » Guía: documentando tu código en Swift
Documentar código

Guía: documentando tu código en Swift

Documentar el código, eso que pocos hacen pero que al final resulta extremadamente necesario. No solo porque podamos o no trabajar con más gente, sino porque en la reutilización de nuestro propio código, estos pequeños pasos nos pueden facilitar mucho la vida a la hora de tener que “bucear” en busca de cómo se invocaba, qué parámetro tenía o para qué servía tal o cual función, clase, objeto, variable o lo que sea que vayamos a usar.

Paso 1, accediendo a la información

Tanto en un playground como dentro de un proyecto de Xcode tenemos una “herramienta mágica” que nos facilitará la vida en más de una y más de dos ocasiones, ahorrándonos buscar la información por otras vías como “googlear” o acceder a la documentación. Algo tan simple como pulsar la tecla ALT (u option) y sin soltarla pulsar en una clase, una llamada, una variable… cuando haya información, veremos que el cursor se convierte en un pequeño interrogante: pulsamos y ¡magia!.

Quick Help

Este es el acceso a la ayuda inline o Quick Help (ayuda rápida) que nos permite acceder a los datos e información que haya de algún elemento. Por ejemplo, saber en qué fichero se definió una variable y el tipo que es (lo que resulta muy útil cuando el sistema lo infiere), conocer los parámetros de una clase, la declaración de una función…

Además disponemos de una serie de hiperenlaces, a modo web, que nos permiten navegar directamente hasta las definiciones o declaraciones de dichos elementos dentro de la documentación instalada en el sistema.

Si no os apareciera la documentación es porque debéis instalarla aparte, por lo que en Xcode id a Xcode > Preferences y luego a la pestaña Downloads. En la parte inferior están los accesos a Documentation, donde os aconsejamos bajar la de Xcode, además de la del sistema con que trabajéis, iOS u OS X.

Paso 2, generando nuestra propia documentación

Ya conocemos Quick Help. Pero, ¿sabes que tú mismo puedes proveer la información de esta opción para tus propias clases o funciones de una manera muy simple? Para ello se usan formatos concretos de comentarios antes de aquello que queremos documentar.

Pero aquí es donde empiezan los problemas, porque si bien en Objective-C existe el soporte de las etiquetas HeaderDoc, estándar usado también en C o C++ y que permite grandes posibilidades y versatilidad con la documentación, en Swift las opciones son bastantes pobres y escasas usando parcialmente otro estándar denominado reStructuredText.

En ambos lenguajes, no obstante, el lugar donde ubicar la documentación es el mismo: antes de la declaración de una función, clase o incluso variable. Se incluye una línea o un bloque de comentario antes y de esta forma se generará la ayuda rápida.

De esta manera tan simple hemos incluido una descripción a nuestra variable, de forma que cuando la usemos en cualquier otro sitio del código y accedamos a la ayuda rápida, veremos junto a ella la descripción que hemos dado.

Descripción Quick Help

En Swift es así de simple: escribir o bien una sola línea como ya hemos hecho con tres /// o un bloque de varias líneas donde la primera línea es /** y la última es */ Dentro de dicho bloque escribimos el contenido que queramos que formará parte de la descripción. También podemos usar etiquetas que estén entre símbolos de : para crear subsecciones dentro de la descripción.

Existen también dos secciones aparte de la descripción que podemos usar con sus correspondientes etiquetas: :param: seguido del nombre del parámetro y su descripción y :returns: seguido del tipo que devuelve (en caso que devuelva algo) y la correspondiente descripción.

Quick Help Swift

Podemos incluir lista ordenadas de elementos que nos ayuden a formatear un poco más el resultado y hacer el uso ya comentado de las subsecciones dentro de la descripción, por ejemplo.

Quick Help 2

Las listas ordenadas pueden usar asteriscos para crear listas de puntos, guiones o incluso números.

Si queremos incluir varios parámetros usamos el mismo formato en diferentes líneas: primero el comando :param:, luego el nombre del mismo y seguido su descripción. Puestos uno debajo de otro, los formateará dentro de su correspondiente sección y en el orden indicado.

Podemos documentar cualquier elemento, desde clases completas, extensiones, protocolos… cualquier cosa a la que (antes de su creación) antepongamos esta estructura de comentarios que genera la ayuda rápida de manera automática.

Las ayudas se generan automáticamente mientras escribimos por lo que no es necesario recompilar ni reconstruir el proyecto. Si accedemos a la ayuda desde el mismo fichero se actualiza solo y si lo hacemos desde otro, con grabar el archivo con CMD+S será suficiente para que todo se actualice.

Paso 3: poniendo marcas en el código

Lo último que vamos a aprender, que tiene también bastante utilidad, es la forma de poner marcas en nuestro código que luego nos ayuden a recordar determinadas cosas o clasificar largos ficheros por secciones.

En este caso podemos poner marcas de referencia en el código (al estilo de la directiva #pragma en Objective-C) que nos permiten crear nuestra propia clasificación del código a la hora de navegar por él. Podemos usar anotaciones de tareas pendientes en el código o incluso avisos de correcciones que hemos de realizar, para nuestro propia ayuda y recordatorio o la de otros.

Se realiza usando un comentario convencional que se inicie con // seguido de las palabras clave MARK:, TODO: o FIXME:.

Con esta simple línea estamos marcando que algo hay que hacer. Cuando desplegamos la lista de componentes de la clase en la parte superior del código, vemos que el mensaje aparece.

Marcas de código

Si usamos MARK veremos una especie de cabecera en un punto determinado que nos podrá indicar donde comienza una determinada sección de una clase (imaginad decenas de funciones de una clase una debajo de otra) y FIXME nos alertará sobre cosas que haya que realizar. Pulsando en ellos en la lista, navegaremos automáticamente al punto del código donde está esa marca.

Toda esta información la tendremos accediendo desde la parte de navegación que se encuentra sobre el código, pulsando a la derecha del nombre del fichero con que estemos trabajando. De esta forma, etiquetar y navegar por nuestros ficheros será mucho más práctico y rápido.

Conclusiones

En Swift, lo que ganamos en facilidad y ser más prácticos, lo perdemos en posibilidades y versatilidad: perdemos la opción de hacer cosas como generar un fichero con nuestra documentación o formatear el contenido con texto enriquecido, así como más opciones mucho más allá de enumerar parámetros o valores de retorno. Aunque por otro lado, sea más fácil.

En otro especial veremos como usar HeaderDoc para documentar el código en Objective-C y vosotros mismos os daréis cuenta de la enorme diferencia y potencial que tiene este frente a la forma mucho más simple de llevar este tema en Swift.

Mientras, seguid probando y probando, y no olvidéis documentar vuestro código: os ayudará a vosotros mismos los primeros y luego a quien trabaje o pueda trabajar con vosotros. Hasta la próximo y Good Apple Coding.

Acerca de Julio César Fernández

Analista, consultor y periodista tecnológico, desarrollador, empresario, productor audiovisual, actor de doblaje e ingeniero de vídeo y audio.

Otras recomendaciones

Prototipos Unit Testing TDD

Lecciones por prototipos (II): test unitarios (XCTest y TDD)

Una de las cosas que normalmente se perciben más complejas en el desarrollo en cualquier …