Una de las tareas a la que menos tiempo dedicamos los desarrolladores (y yo me incluyo) es a escribir documentación en nuestro archivos de código fuente Swift.
Bien por falta de tiempo o por dejadez siempre dejamos de añadir comentarios que llegado el día que tengamos que modificar ese mismo archivo nos serían muy útiles para entender qué hacía esa función o porqué habíamos puesto ese bucle en ese momento determinado.
Los ingenieros de Swift, sabedores de ese pequeño defecto que tenemos, añadieron un soporte estupendo al lenguaje para que pudieramos añadir ayuda a nuestro código y que además interactue con Xcode. Así que vamos a dar un repaso a todas las opciones que tenemos y a ver cómo añadirlas a nuestros archivos.
Todo comienza con Markdown
En lugar de crear un lenguaje de marcado propio, los creadores de Swift decidieron que era mejor emplear uno existente y de amplia difusión, así que dotaron a los comentarios del lenguaje de soporte Markdown.
Markdown es un lenguaje de marcado ligero creado por John Gruber que trata de conseguir la máxima legibilidad y facilidad de publicación tanto en su forma de entrada como de salida.
Es decir, que junto con nuestro texto plano podemos incluir los marcadores de Markdown para dar un formato más profesional a nuestros comentarios.
A continuación os dejo una pequeña guía con la sintáxis básica de Markdown. Al final del artículo encontraréis un enlace con una guía más detallada por si os interesa o la necesitáis.
Encabezados
Siempre deben ir al inicio del párrafo.
| Marcador | ¿Para qué sirve? | Ejemplo |
|---|---|---|
| # | Indica el título principal | # Título 1 |
| ## | Nivel 2 de título | ## Título 2 |
| ### | Nivel 3 de título | ### Título 3 |
| #### | Nivel 4 de título | #### Título 4 |
| ##### | Nivel 5 de título | ##### Título 5 |
| ###### | Nivel 6 de título | ###### Título 6 |
El resultado sería…
Título Principal
Título 2
Título 3
Título 4
Título 5
Título 6
Sólo hay disponibles seis niveles de titulado.
Negrita
| Marcador | ¿Para qué sirve? | Ejemplo | Se ve como… |
|---|---|---|---|
| ** | El texto en negrita se pone entre los 2 asteriscos | Es muy **importante** | Es muy importante |
| __ | En luga de asteriscos se puede usar el guión bajo | Es muy __importante__ | Es muy importante |
Cursiva
| Marcador | ¿Para qué sirve? | Ejemplo | Se ve como… |
|---|---|---|---|
| * | El texto en cursiva se pone entre un solo asterisco | Es muy *importante* | Es muy importante |
| _ | En luga de asteriscos se puede usar un guión bajo | Es muy _importante_ | Es muy importante |
Citas
| Marcador | ¿Para qué sirve? | Ejemplo |
|---|---|---|
| \> | Se pone al principio del párrafo de cita | \> En un lugar de la Mancha… |
Se vería así
En un lugar de la Mancha…
Listas
Podemos generar listas ordenadas, desordenadas y en ambos casos podemos anidar listas dentro de otras. Vamos a verlo.
| Marcador | ¿Para qué sirve? | Ejemplo |
|---|---|---|
| + | Se pone antes de elementos de la lista | + Item |
| – | Se pone antes de elementos de la lista | – Item |
| * | Se pone antes de elementos de la lista | * Item |
Para anidar los elementos tenemos que añadir una tabulación al elemento para establecer la jerarquía. Por ejemplo…
– Diseño
– iOS
– Mac
– Web
– Desarrollo
– Interface
– Controladores
– Framework
– Despliegue
Se ve como…
- Diseño
- iOS
- Mac
- Web
- Desarrollo
- Interface
- Controladores
- Framework
- Despliegue
Las listas ordenadas se crean usando números seguidos por un punto como indicador de elemento. Es importante que el primer elemento sea siempre el número 1, el resto no tienen porque ir en orden. Por ejemplo…
1. Pruebas
1. iOS
2. Mac
3. Web
2. Despliegue
1. App Store
2. Mac App Store
3. Envío de Press Kit
4. Seguimiento
Se ve como…
- Pruebas
- iOS
- Mac
- Web
- Despliegue
- App Store
- Mac App Store
- Envío de Press Kit
- Seguimiento
Código embebido
Encerrando el código entre el caracter ` marcamos esa parte del texto como código fuente. Por ejemplo, ` let nombre = “Adolfo” ` se vería como let nombre = "Adolfo"
También podemos añadir código de más de una línea, incluso podemos indicar el lenguaje en el que lo estamos escribiendo. Para ello debemos encerrar el parrafo con el código con los tres caracteres ` y en el de apertura indicamos el lenguaje. Por ejemplo…
` ` ` swift
override internal func viewDidLoad() -> Void
{
super.viewDidLoad()
}
` ` `
Se vería como…
override internal func viewDidLoad() -> Void
{
super.viewDidLoad()
...
}
Hay que tener en cuanta que el soporte para resaltado de lenguaje no está disponible en todos los visores de Markdown.
Documentación con Swift
Ahora que sabemos como darle formato a nuestra documentación vamos empezar de documentar nuestro código. El primer ejemplo que vamos a ver es muy sencillo, simplemente vamos a meter una lista en el comentario de un Enum y a documentar sus variables.
Podéis ver el código completo en este archivo de GitHub.
Documentar Parámetros, Variables de Retorno y Throws.
Esto es lo que va a ocupar el 99% del tiempo que pasemos documentando nuestro código. Lo primero que necesitamos saber es que para documentarlos necesitamos usar unos marcadores específicos.
Parámetros
El marcador para los parámetros es -Parameter y su formato es:
-Parameter nombreVariable: Y aquí su descripción
-Parameter otraVariable: Y aquí otra descripción
o también podemos usar -Parameters en cuyo caso el formato varía
-Parameters:
-nombreVariable: Y aquí su descripción
-otraVariable: Y aquí otra descripción
Podéis ver el código completo en este archivo de GitHub.
Throws
Si nuestra fución lanza un error podemos documentar los diferentes tipos de errores mediante el marcador Throws seguido de la lista de errores que podemos generar y una descripción de cada uno de ellos.
- Throws:
- serverUnavailable: Server is not ready
- badRequest: The `StoreRequest` objet is not well-formed
Valores de Retorno
Si la función devuelve un valor éste se puede documentar con el marcador Return seguido de la descripción de lo que se devuelve por parte de la función
- Returns: El stream con un formato `JSON` válido
Podéis ver el código completo en este archivo de GitHub.
Otros marcadores
Además de los los vistos anteriormente hay otros marcadores que puden sernos de utilidad a la hora de hacer notar alguna particularidad en nuestro código.
SeeAlso
Añade un referencia a otras funciones, tipos, etc. del código
- SeeAlso: `fetchTicket(_:)`
Precondition
Describe el estado necesario para que se pueda ejecutar la función
- Precondition: Debemos tener un *token* válido del servidor
Postcondition
Describe el estado en el que debe quedar el sistema tras ejecutar la función
- Postcondition: Tenemos un ticket válido tras la compra
Requires
Los requisitos para una ejecución correcta del código.
- Requires: Que `startDate` sea menor que `endDate`
Version
Un número de versión del código
- Version: 1.0.1
Warning
Una advertencia sobre el uso o estado del código
- Warning: Cualquier ticket anterior se sobreescribe al terminar.
Important
Hacemos notar algo importante a todo aquel que use este código.
- Important: Se procede al cargo del importe del ticket mediante **Apple Pay**
Complexity
Indica la complejidad del algoritmo a la hora de ejecutarse para que nos hagamos una idea cómo puede influir en el rendimiento de la app o framework.
- Complexity: O(n)
Documentar el Acerca de…
Existen otros marcadores que sirven para que podamos indicar información tal como el autor o autores del código, el copyright, notas sonre lo que se ha escrito… No es información sobre el código en si, pero nos puede servir por si necesitamos ponernos en contacto con quien escribió ese código.
Author
El autor o autores del código
- Author: Adolfo Vera (@fitomad)
O si son varios los autores…
- Authors:
- Adolfo Vera
- Jorge Vera
Copyright
Información sobre los derechos de autor o la licencia a la que está sujeto el código
- Copyright: 2018 Adolfo Vera. MIT License
Date
Una fecha, puede ser la de creación, la de última modificación…
- Date: Created -> 02/12/2018 Modified: 03/12/2018
Keyword
Se usa para establecer palabras claves por las que puede buscar que no están presentes en la descripción del código.
- Keyword: TicketMaster, Star Wars, The Big Bang Theory, Apple Pay.
Note
Es información relacionada sobre el código.
- Note: Cualquier problema con el token hay que dirigirse a Sistemas.
¿Y cómo veo esto en Xcode?
Sólo tienes que pulsar con el ratón o el trackpad en el nombre de la función, clase, estructura… mientras pulsas la tecla OPTION en tu teclado. Al hacerlo verás algo como esto:
Creando secciones en el código
Si habéis escrito código en Objective-C seguro que os suena la directiva del preprocesador #pragma mark. Pues bien, en Swift tal directiva no existe, pero si que tiene un homólogo en forma del // MARK: o // MARK: - si queremos incluir una barra de separación horizontal en el explorador de funciones de Xcode.
Con esto podemos crear secciones en nuestro código que nos van a permitir navegar por él de una forma más cómoda y sencilla. Vamos a verlo con un ejemplo, primero vamos a ver el código y luego podrás ver una imagen del explorar de funciones de Xcode donde verás como divide las diferentes secciones.
Y en Xcode veremos…
Conclusión
Y recordad añadir comentarios, vuestro yo del futuro os lo agradecerá eternamente.
Enlaces de interés
- Guía de la sintaxis de Markdown.
- Cálculo de la complejidad de un algoritmo