Codice "auto esplicante" e commenti

[DragoRosso]

Leggendo tra vari forum, e andando a verificare qualche mio codice scritto nel passato (neanche tanto "passato") ho toccato un argomento sicuramente spinoso tra i programmatori: il commento al codice.

Tutti, nessuno escluso, siamo partiti a scrivere codice per un nuovo progetto proponendoci:

... questa volta commento bene il codice e che sia da base per il futuro ...

Poi presi dal poco tempo, dagli imprevisti della programmazione, ... chi è rimasto senza benzina ... chi aveva una gomma a terra ... chi aveva il funerale della madre ... era crollata la casa ... c'è stato un... terremoto, una tremenda inondazione, le cavallette!  (citazioni dai mitici "Blues Brothers") ... insomma per mille motivi non l'abbiamo fatto.

Poi come autodifesa, più che altro per zittire la coscienza, ci siamo detti: "ma certo non servono commenti, il codice si commenta da solo, è talmente ovvio e chiaro".

Ora, appunto riprendendo parti di codice scritti tempo fà mi sono reso conto che i commenti servivano eccome !

Riuscire a capire che cosa passava per la testa in quel momento (tempo fà), è quasi impossibile. Ogni tanto mi chiedo che cosa stessi fumando quando scrissi "quel codice"...

Penso siano esperienze comuni, soprattutto per chi lo fà di professione scrivendo molti programmi.

In Delphi si usano delle tecniche non supportate da Lazarus / FPC (come le procedure all'interno delle procedure, chiamate procedure anonime) che una volta sviluppate, se non commentate possono effettivamente far perdere molto tempo durante la manutenzione del codice.

Lo stesso Delphi fornisce un aiuto notevole usando XMLDoc nel codice, quindi con una semplice linea possiamo commentare facilmente sia come commento al codice che come commento a chi userà quel codice (viene proposto quando usi quella variabile / tipo / metodo con un commento XMLDoc), ma comunque i commenti scarseggiamo.

Insomma per chiudere, commentiamo il codice ... meglio un commento in più che uno in meno ... e non è che bisogna commentare ogni linea ma almeno esponiamo per blocchi quali sono le nostre intenzioni, perchè è stato fatto così piuttosto che colà.

Con questa riflessione Vi porgo un saluto e ... "Buona programmazione" a tutti.

[bonmario]

Ora, appunto riprendendo parti di codice scritti tempo fà mi sono reso conto che i commenti servivano eccome !

Questo succede spessissimo. Io me lo sono motivato così: probabilmente quando lo stai sviluppando, sei talmente "dentro" all'argomento, che certe cose ti sembrano ovvie.
Poi non le vedi più per mesi/anni, e quando le riprendi in mano, ti rendi conto che erano ovvie in quel momento, ma ora non lo sono più !

Riuscire a capire che cosa passava per la testa in quel momento (tempo fà), è quasi impossibile. Ogni tanto mi chiedo che cosa stessi fumando quando scrissi "quel codice"...

Secondo me, questo dipende soprattutto dall'esperienza: anche io, quando prendo in mano programmi che ho fatto qualche anno prima, mi insulto da solo, perché più passa il tempo, più impari a fare meglio.
Se non fosse così, ci sarebbe da preoccuparsi: vuol dire che non stai evolvendo.

Lo stesso Delphi fornisce un aiuto notevole usando XMLDoc nel codice, quindi con una semplice linea possiamo commentare facilmente sia come commento al codice che come commento a chi userà quel codice (viene proposto quando usi quella variabile / tipo / metodo con un commento XMLDoc), ma comunque i commenti scarseggiamo.

Credo che ci sia qualcosa di simile anche in Lazarus (non ho mai usato Delphi): se usi Synapse, ad esempio, potrai notare che i commenti che ci sono sopra alle varie propietà, ti escono come Hint quando usi quelle proprietà, e ti ci fermi sopra con il mouse.


Ciao, Mario

[xinyiman]

Se ancora non lo hai letto ti consiglio il libro clean code. Affronta l'argomento in maniera egregia.

[DragoRosso]

Se ancora non lo hai letto ti consiglio il libro clean code. Affronta l'argomento in maniera egregia.

Non mancherò. Ne ho letti altri sull'argomento, e nonostante anche io predichi bene ... alla fine finisco sempre per razzolare male. Partono i commenti a tutto spiano e poi lungo il progetto si "diradano" come neve al sole ... però prima o poi sono convinto che riuscirò a commentare un intero progetto (magari un "Hello World" ...  )

[DragoRosso]

Lo stesso Delphi fornisce un aiuto notevole usando XMLDoc nel codice, quindi con una semplice linea possiamo commentare facilmente sia come commento al codice che come commento a chi userà quel codice (viene proposto quando usi quella variabile / tipo / metodo con un commento XMLDoc), ma comunque i commenti scarseggiamo.

Credo che ci sia qualcosa di simile anche in Lazarus (non ho mai usato Delphi): se usi Synapse, ad esempio, potrai notare che i commenti che ci sono sopra alle varie propietà, ti escono come Hint quando usi quelle proprietà, e ti ci fermi sopra con il mouse.

Ciao, Mario

Vedi l'allegato ... in Delphi puoi farlo su qualsiasi cosa ed è una figata. Consente di descrivere non solo Summary e Remarks come nell'esempio ma anche parametri di ingresso e uscita, valori, funzioni interne, etc ...
Poi quando sviluppi hai tutto a disposizione, senza cercare nei riferimenti o nei vari sorgenti ... questa è una delle cose (non la principale ovviamente) che purtroppo non mi fà abbandonare Delphi a favore di Lazarus.

Ciao

[nomorelogic]

volevo segnalare questo progetto
https://pasdoc.github.io/

pagina wiki lazarus/free pascal
https://wiki.freepascal.org/PasDoc

pasdoc è abbastanza conosciuto ed ampiamente utilizzato

purtroppo ho anche io la sindrome del "questa-volta-documento-tutto-bene-ma-in-realtà-non-accadrà-mai" 
ma devo riconoscere che il progetto è ben fatto


Edit:
che poi...
è un progetto per la documentazione del software che è ben documentato
c'è da imparare 

[tito_livio]

D'accordissimo su tutto. Volevo solo aggiungere che per la chiarezza del codice conta anche come lo si scrive.
Per molti sarà ovvio ma mi sono trovato abbastanza in difficoltà, dovendo fare manutenzione a progetti non fatti da me.
Si va dal codice non indentato bene e qui Lazarus mette a posto, per fortuna.
Poi le variabili e le procedure con nomi assurdi che non riconducono a cosa servono.
Mettici le parti di procedura lunghissime, senza suddivisione in sotto procedure e ciliegina sulla torta le form con tutti i componenti, visibili e non, ammucchiati random.
Così, spesso, prima lo sistemo un po' e poi cerco il baco.
Dimenticavo, un paio di volte ho trovato pure il goto...

[bonmario]

Poi le variabili e le procedure con nomi assurdi che non riconducono a cosa servono.

Una delle cose che non sopporto, sono le variabili col nome di uno o 2 caratteri.
Quando poi le devi cercare, nomini tutti i santi del calendario !!!

Ciao, Mario