Apple

Entre todas las características que Xcode 7 incorpora, hay uno que se distingue; y es la nueva y revolucionaria forma para escribir la documentación del código. Con la introducción de Xcode 7 los desarrolladores pueden utilizar la sintaxis Markdown para aplicar formato de texto enriquecido en su documentación, que en combinación con las palabras claves (como parámetros, resultados de función, etc) puede dar lugar a un sorprendente resultado. Se proporciona un mayor nivel de personalización del texto, es más flexible y, por supuesto, más interesante.

Documentar el código es una tarea extremadamente importante para todos los desarrolladores. A pesar de que parece que se cala el proceso de desarrollo, es en realidad una parte de ella. No voy a estar en desacuerdo que escribir la documentación apropiada y completa para cada propiedad individual, función, clase, estructura, o cualquier otra cosa que existe en un proyecto no es un trabajo fácil. Sin embargo, escribiendo la documentación apropiada se puede:

• Describir el propósito de las propiedades, funciones y clases hasta el nivel de detalle que se desea. Por otra parte, es el mejor lugar para describir las condiciones, casos o requisitos para sus funciones.
• Resaltar las entradas y salidas (parámetros y valores de retorno) de sus métodos.
• Recordar lo que cada función se supone debe hacer y para que sirve cada propiedad y lograr de esta manera que al visitar unos meses después tu aplicación puedas entender lo que hace la misma.
• Que sea fácil para otros desarrolladores entender cómo usar el código cuando se comparte o hacer sus propias bibliotecas.
• Producir manuales de aspecto profesional utilizando herramientas hechas para esta razón (por ejemplo Jazzy).

(more…)