Etiquetes

,

La divulgació de la feina que fem els programadors és complicada: moltes vegades, fins i tot per nosaltres mateixos. I el fet de documentar el codi no és el comú denominador dels programadors, tot i que hauria de ser un element indispensable de qualsevol codi font que s’hagi de compartir.

En tot cas, també de vegades tenim excusa: la manca de temps per executar un projecte fa que, per una banda, haguem d’estalviar moments en què redactaríem completes explicacions del seu funcionament. A més, la contínua actualització d’alguns d’aquests codis fan inviable el manteniment d’una documentació prou “al dia”, de manera que cal anar-la actualitzant cada cert temps… i després no sempre es fa prou sovint, deixant encara alguns apartats sense prou explicacions.

Es tendeix a pensar que “com que ho he escrit jo ja ho recordaré”. Per una banda, això per si sol ja no és cert: m’he perdut completament en codis sense comentar prou bé que havia escrit jo mateix; però potser feia 4 o 5 anys. Massa temps, i massa línies significa un temps perdut en reunir la informació necessària a base de llegir codi; que després he corregit tot indicant, en dues línies de comentaris, el què més endavant podré necessitar saber per estalviar temps.

Volia aprofitar aquest tema per parlar d’un sistema de documentació que vaig veure en un twitt de l’Àlejando Martínez fa força temps, però que em va quedar pendent. Podeu fer el mateix recorregut que es proposava: un article, The most important code isn’t code, amb enllaços a un mètode de documentació TomDoc, prou interessant de llegir.

Potser no és el millor ni el definitiu, i potser cal adaptar-lo: però si que és necessari tenir el codi ben comentat, tant si hem de pensat que nosaltres l’utilitzarem, com si algú altre l’ha d’acabar intentant llegir. La documentació és important, tot i que, sovint, sembli una tasca secundària.

Anuncis