Comenta, que serveix
Quan un fa programes per aprovar l'assignatura sap que ha de posar comentaris perquè si no no és considera un codi professional, així que els posam per obligació, perquè hi han de ser, però potser sense adonar-nos de la seva utilitat real.
Els programes que feim per aprovar rarament són molt complexos, són exemples que es poden fer en poques setmanes i que rarament s'hauran de mantenir. La vida real és força diferent, els programes tenen un cicle de vida llarg, d'anys o dècades i s'han de fer millores correctives i adaptatives.
Aquell programa que ahir teníem molt clar al cap d'uns anys potser ja no ho tindrem tant i els comentaris que posàrem faran que tot ens resulti molt més fàcil d'entendre. I ja no diguem res si no som nosaltres el que hem de mantenir el codi!
Els bons comentaris ens haurien de dir el perquè del codi, què fa, què espera a l'entrada i què a la sortida. El codi ens dirà com ho fa. Això vol dir que el codi també ha de ser llegible, teclejar una mica més no costa tant i podem posar noms a les variables, a les classes, a les funcions, que tenguin significat.
Python per exemple té dues castes de comentaris, els que es fan servir per documentar el per què, i que sovint es presenten en forma de cometes triples i que es lliguen al doc (i a l'ajuda) de l'objecte i els comentaris fets amb la parrilla (#) que s'han de fer servir per comentar aspectes del codi que no necessitin. Java té quelcom semblant.
Però podem anar una mica més enllà. L'altra dia al twitter algu deia que li quedava fer la documentació de la pràctica. També molt habitual :) Posar bons comentaris ens pot estalviar una bona feina i no tan sols això, sinó que serà text de qualitat ja que s'ha fet amb menys presses i amb la ment més fresca en relació al que se està fent.
I encara una utilitat més: el pseudocodi. Particularment quan he de fer una cosa complexa començ per escriure'n les passes i les pos en forma de comentari. D'aquesta manera tenim més clar el que s'ha de fer i el temps s'aprofita, ja que aquest pseudocodis seran després els comentaris que ajudaran a seguir millor el codi.
No vull acabar sense citar una eina fantàstica per a la documentació: l'Sphinx us podeu adonar d ela bona feina que fa amb la documentació de Python o Django per exemple. Sphinx té una cosa molt bona, ens permet extreure els comentaris del nostre codi Python i afegir-los a la documentació, de manera que du el reaprofitament i la màxima DRY al món dels comentaris i la documentació. Per poc que us agradi el RestructuredText no deixeu de fer-li una ullada a aquesta eina, fins i tot si no programau en Python.
Per cert, en el seu dia vaig deixar un petit tutorial de RestructuredText a Bulma.
