Tidy First?

Capitolo 15. Eliminare i commenti ridondanti

Questo lavoro è stato tradotto utilizzando l'AI. Siamo lieti di ricevere il tuo feedback e i tuoi commenti: [e-mail]

Quando vedi un commento che dice esattamente quello che dice il codice, rimuovilo.

Lo scopo del codice è quello di spiegare agli altri programmatori cosa vuoi che faccia il computer. I commenti e il codice presentano diversi compromessi per te come scrittore e per i futuri lettori. In prosa puoi spiegare tutto ciò che vuoi. D'altra parte, non c'è un meccanismo per ricontrollare l'accuratezza della prosa quando il sistema cambia e i commenti potrebbero diventare ridondanti con l'evoluzione del codice.

Alcune persone hanno una visione ristretta del mandato di comunicare, insistendo su regole dogmatiche come quella che afferma che ogni routine deve essere commentata. Questo porta a commenti come:

getX()
  # return X
  return X

Questo commento fornisce costi senza benefici. Come scrittore, hai appena fatto perdere tempo al lettore, tempo che non potrà recuperare. Se un commento è completamente superfluo, cancellalo.

I Tidy spesso collegano tra loro . Un precedente riordino potrebbe aver reso superfluo un commento. Ad esempio, il codice originale potrebbe essere simile a questo:

if (generator)
    ...a bunch of lines of code to set up the generator...
else
    # no generator, return the default
    return getDefaultGenerator()

Dopo aver messo in ordine con una clausola di guardia, il codice si presenta in questo modo: ...