"Commenta tutto nel modo giusto" e "Invece di scrivere commenti, scrivi codice più leggibile." - Entrambe le strategie valide?

La tua domanda implica una dicotomia che non esiste.

Dovresti scrivere un codice più pulito, se così facendo lo renderà abbastanza chiaro dove non devi documentarlo? Assolutamente.

Dovresti scrivere commenti e altrimenti fornire documentazione, quando migliorerà la chiarezza e la comprensione del codice? Certo.

Perché queste due cose non si escludono a vicenda?

1. Alcuni dei codici che scrivi favoriscono le migliori prestazioni rispetto alla leggibilità.
2. L'architettura non è auto-documentante. Mentre il codice in isolamento è generalmente abbastanza facile da capire se è scritto in modo pulito, l'architettura che lo circonda non è sempre.
3. Le decisioni di progettazione non sono sempre evidenti.
4. Quale processo aziendale o problema risolve il codice non è sempre evidente.

In breve, non è possibile scrivere codice non banale in modo tale che sia sempre completamente auto-descrittivo. Parte del tuo lavoro consiste nell'assicurare che l'individuo che viene dopo di te non ha bisogno di un anno per capire il tuo codice e, per questo, una buona documentazione è una necessità.

A volte puoi scrivere codice leggibile che richiede ancora qualche spiegazione aggiuntiva. Di solito questi rispondono alle domande perché o mettono in guardia contro la sicurezza o altri tipi di problemi che potrebbero non essere ovvi. Ad esempio, ho scritto un commento la scorsa settimana spiegando che una chiamata a glob.glob precedente a una chiamata a subprocesso.check_call è stato per evitare di specificare shell=True , che è un rischio per la sicurezza.

Senza quello, un futuro manutentore potrebbe pensare che l'ho reso inutilmente complesso. Lo avrebbero rifattorizzato, quindi il check_call fallirebbe. Andrebbero ai documenti, scoprono che hanno bisogno di shell=True , e speriamo di vedere il grande avvertimento rosso lì. Quindi, nel migliore dei casi, il mio commento ha salvato un futuro manutentore. Nel peggiore dei casi, ha salvato un buco di sicurezza accidentale.

Nota comunque che sta dicendo qualcosa che posso ricordare l'ultimo commento che ho scritto. Queste situazioni non sono particolarmente frequenti.

Passare attraverso questo link , può aiutarti.

La documentazione è necessaria, ma commentare per ogni variabile, per loop, la parte di codice non è necessaria. Descrivere cosa fa la funzione, input accettabili e tipo previsto di o / p ecc. Al momento della dichiarazione, descrivendo la funzionalità complessiva di un file, l'entità del mondo reale che simula, ecc. È utile. Questo aiuta i futuri programmatori a scrivere codice mantenibile.

Ma i nomi delle funzioni, dei file, delle variabili, ecc. dovrebbero essere auto-descrittivi. Ciò aiuta il lettore del programma, in quanto le persone che non hanno subito le conseguenze, tendono a ignorare affermazioni che non sono eseguibili. Inoltre, i lettori sono di fretta, di solito non vogliono leggere cose extra. Esempio di base: in caso di più valori possibili di una variabile, che devono essere gestiti in modi diversi, l'utilizzo di un'istruzione switch-case lo descriverà meglio di una catena di if-else-else. Nel caso successivo, potresti dover dare un commento, nel primo caso il codice sta descrivendo l'idea alla base.

Nei luoghi in cui i nomi e lo stile di codifica non descrivono il codice in modo corretto e l'utilizzo di uno stile di codifica alternativo può influire sulle prestazioni, è possibile utilizzare i commenti.