Clean code, Comments

by nicola aramini

Posted on settembre 18, 2017 at 10:24 AM

Comments

Veramente spesso mi trovo a discutere con i colleghi sui commenti.

C’è chi li vuole sempre e comunque su ogni riga, chi li vuole solo a volte (a discrezione di chi non si sa), o addirittura chi non li vuole mai, mai, mai, mai.

La domanda sorge spontanea… Come ci si deve comportare?

Come spesso accade, la risposta è: DIPENDE.

La prima considerazione che mi viene in mente riguarda il seguente codice:

//ritorna tutte le shape

public List<Shape> GetAllShapes(){…}

A cosa serve questo commento?

Qual è il valore aggiunto che mi sta dando?

Quando cambio una riga il costo “schizza”: oltre alla riga devo tenere aggiornato il commento, ma questo non succede mai.

Risultato? il commento non è mai aggiornato rispetto al codice scritto.

Se so che non è aggiornato, nella migliore delle ipotesi lo ignoro, ma il problema vero sorge quando il commento dice una cosa ma poi il codice ne fa una diversa e tu non hai mai visto quel progetto, avrà ragione il commento o il codice?

In questo caso i commenti vanno evitati o se li trovate, cancellateli senza pietà!

La seconda considerazione è che spesso devo fare azioni (richiamare un metodo particolare in alcuni casi) e non è molto chiaro il perché: magari per risolvere un bug che si presenta solo in certe condizioni.

In questi casi (spero per voi siano molto pochi) i commenti per descrivere il PERCHÉ, non il come, sono utilissimi, anzi indispensabili!

Quanto spesso avete visto codice commentato solo per tenerne traccia?

Questi commenti vanno tolti, per vedere versioni vecchie di un metodo o di una classe è molto meglio affidarsi al source control.

Il trucco più importante sui commenti (se non avete seguito gli accorgimenti di cui sopra) è rimuoverli in fase di refactoring.

Il codice:

//prendo gli elementi attivi nella lista

list.Where(i => i.IsEnabled);

//rimuovo i valori vuoti

list.RemoveAll(i => string.IsNullOrWhiteSpace(i.Desc));

//scrivo sul file i valori

..logica per scrivere su file…

può essere rifattorizzato con:

var enableItems = GetEnableitems(list);

var listWithoutEmptyItems = RemoveEmptyItems(enableItems);

WriteOnFile(listWithoutEmptyItems);

 

Questo codice dimostra come spesso i commenti servano per descrivere un concetto.

I concetti devono essere metodi nominati correttamente.

Facendo questo i commenti diventano inutili perché il nome del metodo stesso è il commento: ricadiamo nella prima considerazione scritta in questo articolo.

Quindi la prossima volta che rimarrete impigliati in una discussione sui commenti ricordate:
commenti si solo per descrivere il PERCHÈ non il come!

Come sempre,
Buon lavoro e good coding!


Notizie sull'autore

nicola aramini

Nicola Aramini Hi! I'm Nicola and I'm a .NET software developer at Elfo. I like my job and i like change to improve. In my free time, as often as I can, i go to the conferences and to the events in order to keep me posted on the new topic about software development.