2015/07/11

RTFN

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.
Los tests son autodocumentación, aunque no tengan ningún comentario. Muestran exactamente como se utilizan los artefactos, que reciben y que deben devolver.


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.

No tengo el ímpetu ni el tiempo para hacer los patches necesarios a las herramientas para poder ofrecerlas a sus desarrolladores (no es lo mismo "te propongo una idea" que "te propongo una idea y acá tenés la implementación"), pero estoy dispuesto a secundar a quien lo haga.

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