Tidy First?

Capitolo 14. Spiegare i commenti

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

Hai presente quel momento in cui, leggendo del codice, dici: "Oh,ecco cosa sta succedendo!". Quello è un momento prezioso. Registralo.

Scrivi solo ciò che non era evidente dal codice. Mettiti nei panni del futuro lettore o di te stesso 15 minuti fa. Cosa avresti voluto sapere? Potresti scrivere una nota del tipo: "Quanto segue è complicato dalla necessità di ridurre il più possibile il numero di chiamate alla rete".

Scrivi a qualcuno di specifico, anche se non è molto simile a te. Sei l'unico biologo del tuo team di informatici? Allora faresti meglio a spiegare qualsiasi contesto biologico nel codice, anche se a te sembra ovvio. Il punto è pensare dal punto di vista di qualcun altro e cercare di rispondere in anticipo alle possibili domande.

Se trovi un file con nessun commento di intestazione, considera la possibilità di aggiungere un'intestazione che spieghi ai potenziali lettori perché potrebbero trovare utile la lettura di questo file. (Grazie, AllanMertner).

Il momento in cui si scopre un difetto è un buon momento per commentare. Ad esempio, // Be sure to change ../foo if you add another case. Non è ideale avere questo accoppiamento nel codice. Alla fine dovrai imparare a eliminarlo, ma nel frattempo è molto meglio aggiungere un commento che indichi il problema di accoppiamento, piuttosto che lasciarlo ...