Para mi hay cuatro maneras principales, útiles y necesarias de documentar. Ninguna es descubrimiento mío ni tampoco es novedosa esta agrupación.
Nombres significativos en el código
Esto viene para contrarrestar la práctica iniciada con la falta de
memoria, las tarjetas perforadas y la programación matemática y
científica de usar letras en lugar de nombres. Esta ok usar x,y y z
cuando estás hablando de coordenadas, pero no cuando deberían ser yaOrdenado, cantidadPajaros o nombre.
Esto lo he sacado del dolor de ver código ajeno o propio un tiempo despues.
xDoc (javaDoc, phpDoc, etc [1])
La vida es corta, por favor leé [2], no confundir con xDoc[3]
Intenciones y motivos
¿Por qué elegí sequential search en lugar de binary search? Pues por
que se invoca dos veces en toda la ejecución y son cien elementos, no
vale la pena ordenar.
El código puede ser muy claro, los nombres muy significativos, pero el propósito y los motivos es algo externo al programa o a su código fuente.
Esto lo he aprendido en un excelente curso de arquitectura de sofware en la ECI y el libro del docente que lo dictó [4]
Tests
Los test son de las mejores documentaciones, pues a diferencia de las
anteriores, no se desincroniza con el código. Es común encontrar
ejemplos que no se pueden ejecutar por algún motivo, pero los tests, si
están funcionando, sí se pueden ejecutar, valga la redundancia.
Quizás
esto no cumpla con las normativas, pero si con el pragmatismo de
"código funcionando antes que documentación exhaustiva" [5]
Voy a suponer que aunque no del todo de acuerdo, al menos me has comprendido.
¿Quá hay de malo en:
/**
* Load configuration
*/
void loadConfig() {....}
?
¿Ya viste? ¿No? ¿Y ahora?
/**
* Set date
*/
void setDate() {....}
/**
* Get date
*/
Date getDate() {....}
/**
* XXXX YYYY
*/
void xxxxYyyyyyy() {....}
Es
esto casos es difícil defender xDoc y me frustra el haber usado "nombres
significativos". ¿Para qué voy a ponerle nombre significativo y despues
ponerle lo mismo en la documentación? Me recuerda esta atrocidad:
//increment cycle counter
countC++;
Propongo entonces la incorporación de un nuevo tag xDoc que sea RTFN (Read The Fucking Name)
/**
* @RTFN
*/
void setDate() {....}
Como humanos no tenemos ninguna dificultad en entenderlo y si hiciera falta, se podría enseñar a
xDoc o Doxygen a interpretarlo, cuando lo hallen que pongan en la descripción o el mismo nombre de la función o método o reemplacen según un mapa o una heurística.
El mapa puede tener nombres comunes como
[
"setDate":"Set the date",
"drawButton":"Draw the button"
]
Y la heurística se aprovecharía de camelCase:
setDate -> Set Date
Parece poco, pero la verdad es que poner uno esa documentación es kafkiano.
Gracias por las ilustraciones a Greta[6]
[4] Software Architecture: Foundations, Theory and Practice - Nenad Medvidović y otros http://www.wiley.com/WileyCDA/WileyTitle/productCd-EHEP000180.html
No hay comentarios:
Publicar un comentario