Che cos'è il codice autocompensante e può sostituire un codice ben documentato? [chiuso]

https://stackoverflow.com/questions/209015

03-07-2019
|

Domanda

Ho un collega che insiste sul fatto che il suo codice non ha bisogno di commenti, è " auto-documentazione. "

Ho esaminato il suo codice e, sebbene sia più chiaro del codice che ho visto produrre da altri, non sono ancora d'accordo sul fatto che il codice autocompattante sia completo e utile come pure il commento e il documento documentato.

Aiutami a capire il suo punto di vista .

Che cos'è il codice di auto-documentazione
Può davvero sostituire il codice ben commentato e documentato
Ci sono situazioni in cui è meglio di un codice ben documentato e commentato
Ci sono esempi in cui il codice non può essere auto-documentato senza commenti

Forse sono solo i miei limiti, ma non vedo come possa essere una buona pratica.

Questo non vuole essere un argomento - per favore non menzionare i motivi per cui un codice ben commentato e documentato ha la massima priorità - ci sono molte risorse che lo mostrano, ma non sono convincenti per il mio collega. Credo di aver bisogno di capire meglio la sua prospettiva per convincerlo altrimenti. Inizia una nuova domanda se è necessario, ma non discutere qui.

Caspita, risposta rapida! Leggi tutte le risposte esistenti e fornisci commenti alle risposte anziché aggiungere nuove risposte, a meno che la tua risposta non sia sostanzialmente diversa da ogni altra risposta qui.

Inoltre, quelli di voi che stanno discutendo contro il codice di auto-documentazione - questo è principalmente per aiutarmi a capire la prospettiva (cioè, gli aspetti positivi) degli evangelisti del codice di auto-documentazione. Mi aspetto che altri ti votino se non rimani sull'argomento.

Soluzione

Secondo me, qualsiasi codice dovrebbe essere auto-documentante. In un buon codice auto-documentato, non devi spiegare ogni singola riga perché ogni identificatore (variabile, metodo, classe) ha un chiaro nome semantico . Avere più commenti del necessario in realtà rende più difficile (!) Leggere il codice, quindi se il tuo collega

scrive commenti di documentazione (Doxygen, JavaDoc, commenti XML ecc.) per ogni classe, membro, tipo e metodo E
commenta chiaramente qualsiasi parte del codice che non sia autocompattante AND
scrive un commento per ogni blocco di codice che spiega l'intento o cosa fa il codice a un livello di astrazione più elevato (ovvero trova tutti i file di dimensioni superiori a 10 MB anziché esegui il ciclo di tutto file in una directory, verifica se le dimensioni del file sono superiori a 10 MB, restituisci se vero )

il suo codice e la sua documentazione vanno bene, secondo me. Si noti che il codice autocertificato non significa non che non ci dovrebbero essere commenti, ma solo che non dovrebbero esserci commenti non necessari. Il fatto è, tuttavia, che leggendo il codice (inclusi commenti e commenti di documentazione) si dovrebbe capire immediatamente cosa fa il codice e perché. Se "auto-documentante" il codice impiega più tempo a comprendere rispetto al codice commentato, non è in realtà auto-documentazione.

Altri suggerimenti

Bene, dato che si tratta di commenti e codice, diamo un'occhiata ad alcuni codici reali. Confronta questo codice tipico:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

A questo codice auto-documentante, che mostra cosa viene fatto:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E poi a questo codice documentato, che spiega meglio perché è stato fatto:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E la versione finale del codice come documentazione con zero commenti necessari:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Ecco un esempio di uno stile di commento scadente:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Nell'ultimo esempio, i commenti sono usati quando invece le variabili avrebbero dovuto essere nominate in modo descrittivo, e i risultati di un'operazione sono riassunti quando possiamo vedere chiaramente quale sia l'operazione. Preferirei il secondo esempio auto-documentato a questo ogni giorno, e forse questo è ciò di cui parla il tuo amico quando dice codice auto-documentato.

Direi che dipende dal contesto di ciò che stai facendo. Per me, in questo caso è probabilmente sufficiente il codice auto-documentato, ma è utile anche un commento che descriva dettagliatamente la metodologia alla base di ciò che sta dietro (in questo esempio l'equazione).

Il codice stesso sarà sempre la spiegazione più aggiornata di ciò che fa il tuo codice, ma secondo me è molto difficile spiegare intento , che è il più vitale aspetto dei commenti. Se è scritto correttamente, sappiamo già che cosa fa il codice, dobbiamo solo sapere perché mai lo fa!

Qualcuno ha detto una volta

1) Scrivi solo commenti per codice difficile da capire.
2) Cerca di non scrivere codice difficile da capire.

L'idea alla base di "auto-documentazione" codice è che l'attuale logica del programma nel codice è abbastanza banale da spiegare a chiunque legga il codice non solo ciò che il codice sta facendo, ma perché lo sta facendo.

A mio avviso, l'idea del vero codice autocompensante è un mito. Il codice può dirti la logica dietro ciò che sta accadendo, ma non può spiegare perché viene fatto in un certo modo, in particolare se esiste più di un modo per risolvere un problema. Solo per questo motivo, non può mai sostituire il codice ben commentato .

Penso che sia pertinente chiedersi se una determinata riga di codice sia auto-documentante, ma alla fine se non capisci la struttura e la funzione di una porzione di codice, la maggior parte delle volte i commenti non saranno di aiuto. Prendiamo, ad esempio, la porzione di amdfan di " correttamente commentata " codice:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Questo codice va bene, ma quanto segue è ugualmente informativo nella maggior parte dei moderni sistemi software e riconosce esplicitamente che l'uso di un calcolo newtoniano è una scelta che potrebbe essere modificata qualora qualche altro paradigma fisico fosse più appropriato:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Nella mia esperienza personale, ci sono pochissimi "normali". situazioni di codifica in cui hai assolutamente bisogno di commenti. Con quale frequenza finisci per implementare il tuo algoritmo, ad esempio? Fondamentalmente tutto il resto è una questione di strutturare il tuo sistema in modo che un programmatore possa comprendere le strutture in uso e le scelte che hanno spinto il sistema ad usare quelle particolari strutture.

Dimentico da dove l'ho preso, ma:

Ogni commento in un programma è come una scusa per il lettore. " Mi dispiace che il mio codice sia così opaco che non puoi capirlo osservandolo " ;. Non ci resta che accettare che non siamo perfetti ma ci sforziamo di essere perfetti e di scusarci subito quando è necessario.

Il codice di auto-documentazione è un buon esempio di " DRY " (Non ripetere te stesso). Non duplicare informazioni nei commenti che sono, o possono essere, nel codice stesso.

Anziché spiegare a cosa serve una variabile, rinominare la variabile.

Piuttosto che spiegare cosa fa un breve frammento di codice, estrailo in un metodo e assegnagli un nome descrittivo (forse una versione abbreviata del testo del tuo commento).

Piuttosto che spiegare cosa fa un test complicato, estrailo anche in un metodo e dagli un buon nome.

Etc.

Dopo questo si finisce con un codice che non richiede tante spiegazioni, si spiega da solo, quindi è necessario eliminare i commenti che semplicemente ripetono le informazioni nel codice.

Questo non significa che non hai alcun commento, ci sono alcune informazioni che non puoi inserire nel codice come informazioni sull'intento (il "perché" e "). Nel caso ideale il codice e i commenti si completano a vicenda, ciascuno aggiungendo un valore esplicativo unico senza duplicare le informazioni nell'altro.

il codice autocompattante è una buona pratica e, se fatto correttamente, può facilmente comunicare il significato del codice senza leggere troppi commenti. soprattutto in situazioni in cui il dominio è ben compreso da tutti i membri del team.

Detto questo, i commenti possono essere molto utili per i nuovi arrivati ??o per i tester o per generare file di documentazione / aiuto.

codice autocompattante + commenti necessari contribuiranno notevolmente ad aiutare le persone tra i team.

Prima di tutto, è bello sapere che il codice del tuo collega è in realtà più chiaro di altri codici che hai visto. Significa che probabilmente non sta usando "auto-documentazione" come scusa per essere troppo pigri per commentare il suo codice.

Il codice autocompattante è un codice che non richiede commenti a testo libero per un lettore informato per capire cosa sta facendo. Ad esempio, questo pezzo di codice è auto-documentante:

print "Hello, World!"

e così è:

factorial n = product [1..n]

e così è:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Ora, questa idea di un "lettore informato" è molto soggettivo e situazionale. Se tu o qualcun altro hai problemi a seguire il codice del tuo collega, farebbe bene a rivalutare la sua idea di lettore informato. È necessario assumere un certo livello di familiarità con la lingua e le librerie utilizzate per poter chiamare il codice autocompattante.

L'argomento migliore che ho visto per scrivere "codice auto-documentante" è che evita il problema dei commenti a testo libero che non concordano con il codice così come è scritto. La migliore critica è che mentre il codice può descrivere cosa e come sta facendo da solo, non può spiegare perché qualcosa viene fatto in un certo modo .

In ordine:

Il codice autocompattante è un codice che esprime chiaramente le sue intenzioni al lettore.
Non del tutto. I commenti sono sempre utili per i commenti sul perché è stata scelta una particolare strategia. Tuttavia, i commenti che spiegano che cosa sta facendo una sezione di codice sono indicativi di un codice che non è sufficientemente autocompattante e potrebbe usare alcuni refactoring ..
I commenti si trovano e diventano obsoleti. Il codice ~~dice sempre~~ è più probabile che dica la verità.
Non ho mai visto un caso in cui il che cosa del codice non potesse essere sufficientemente chiarito senza commenti; tuttavia, come ho detto prima, a volte è necessario / utile includere commenti sul perché .

È importante notare, tuttavia, che il vero codice di auto-documentazione richiede molta disciplina di sé e del team. Devi imparare a programmare in modo più dichiarativo e devi essere molto umile ed evitare "intelligente". codice a favore di codice così ovvio che sembra che chiunque avrebbe potuto scriverlo.

Per uno, considera il seguente frammento:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

In questo esempio hai 5 righe di commenti per 3 righe di codice. Ancora peggio: i commenti non aggiungono nulla che non puoi vedere leggendo il codice. Se hai 10 metodi come questo, puoi ottenere la "cecità nei commenti" e non notare l'unico metodo che si discosta dallo schema.

Se ovviamente, una versione migliore sarebbe stata:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Comunque, per codice banale preferisco non avere commenti. L'intento e l'organizzazione generale sono meglio spiegati in un documento separato al di fuori del codice.

Quando leggi un "codice auto-documentante", vedi cosa sta facendo, ma non puoi sempre indovinare perché sta andando in quel modo particolare.

Esistono tonnellate di vincoli di non programmazione come la logica aziendale, la sicurezza, le richieste degli utenti ecc.

Quando si esegue la manutenzione, queste informazioni di backgorund diventano molto importanti.

Solo il mio pizzico di sale ...

Una cosa che potresti voler segnalare al tuo collega è che non importa quanto sia autocompensante il suo codice, se fossero presi in considerazione altri approcci alternativi e scartati, le informazioni andrebbero perse a meno che non commentasse il codice con quelle informazioni. A volte è altrettanto importante sapere che è stata presa in considerazione un'alternativa e perché è stata decisa e i commenti sul codice hanno più probabilità di sopravvivere nel tempo.

Hai mai sentito parlare di " WEB & di Donald Knuth progetto per implementare il suo concetto Programmazione alfabetica ? È più di un codice autocompensante; è più simile alla documentazione che può essere compilata ed eseguita come codice. Tuttavia non so quanto sia usato oggi.

La differenza è tra " cosa " e " come " ;.

Dovresti documentare " cosa " una routine fa.
Non devi documentare " come " lo fa, a meno che non si verifichino casi speciali (ad es. fare riferimento a un documento di algoritmo specifico). Questo dovrebbe essere auto-documentato.

In un'azienda in cui lavoravo, uno dei programmatori aveva i seguenti elementi bloccati nella parte superiore del suo monitor.

" Documenta il tuo codice come la persona che lo sostiene è un maniaco omocida che sa dove vivi. "

Il punto di vista che il codice è auto-documentante mi fa impazzire. Una particolare riga di codice o un sotto-algoritmo può in effetti essere auto-documentante, ma il suo scopo nella figura più grande semplicemente non lo è.

Ne sono stato così frustrato un mese o due fa, ho scritto un intero post sul blog descrivendo il mio punto di vista. Pubblica qui .

il codice di auto-documentazione utilizza normalmente nomi di variabili che corrispondono esattamente a ciò che il codice sta facendo in modo che sia facile capire cosa sta succedendo

Tuttavia, tale "codice auto-documentante" non sostituirà mai i commenti. A volte il codice è troppo complesso e il codice di auto-documentazione non è sufficiente, soprattutto per quanto riguarda la manutenibilità.

Una volta avevo un professore che credeva fermamente in questa teoria In effetti la cosa migliore che mi sia mai ricordato di aver detto è "I commenti sono per femminucce"
All'inizio ci ha sorpreso tutti, ma ha senso.
Tuttavia, la situazione è che anche se potresti essere in grado di capire cosa sta succedendo nel codice, ma qualcuno che ha meno esperienza potrebbe venire dietro di te e non capire cosa sta succedendo. Questo è quando i commenti diventano importanti. So molte volte che non crediamo che siano importanti ma ci sono pochissimi casi in cui i commenti non sono necessari.

Sono sorpreso che nessuno abbia prodotto " Programmazione alfabetica " ;, a tecnica sviluppata nel 1981 da Donald E. Knuth di TeX e "The Art of Computer Programming" fama.

La premessa è semplice: poiché il codice deve essere compreso da un essere umano e i commenti vengono semplicemente eliminati dal compilatore, perché non dare a tutti ciò di cui hanno bisogno - una descrizione testuale completa dell'intento del codice, senza restrizioni requisiti del linguaggio di programmazione, per il lettore umano e codice puro per il compilatore.

Gli strumenti di programmazione alfabetica fanno questo dandoti un markup speciale per un documento che dice agli strumenti quale parte dovrebbe essere fonte e che cos'è il testo. Il programma successivamente strappa le parti del codice sorgente dal documento e assembla un file di codice.

Ne ho trovato un esempio sul web: http://moonflare.com/code /select/select.nw o la versione HTML http://moonflare.com/ codice / select / select.html

Se puoi trovare il libro di Knuth su di esso in una biblioteca (Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, n. 27.) dovresti leggere esso.

Questo è codice auto-documentante, completo di ragionamento e tutto il resto. Perfino fa un bel documento, Tutto il resto è solo commenti ben scritti :-)

La mia opinione è scritta in questo post:

L'unico suggerimento per documenta il tuo codice.

Estratto:

Invece di scrivere molti commenti   per spiegare i comportamenti sottili di   il tuo programma, perché non ristrutturare il tuo   logiche in modo che siano evidenti?   Invece di documentare quale metodo   sta facendo, perché non scegliere un nome chiaro   per quel metodo? Invece di taggare   il tuo codice per indicare il lavoro incompiuto,   perché non semplicemente lanciare un   NotImplementedException ()? Invece di   preoccupante se i tuoi commenti suonano   abbastanza educato per il tuo capo, il tuo   colleghi o chiunque legga il codice,   perché non smettere di preoccuparsi di no   scrivendoli affatto?

Più chiaro è il tuo codice, più facile   è per mantenerlo, per estenderlo, a   lavoraci su future edizioni. Il   meno ordinato è il tuo codice, tanto meno   c'è bisogno di commentarlo. Più   i commenti, maggiore è il   costo di manutenzione.

Vorrei offrire un'altra prospettiva alle molte risposte valide:

Che cos'è il codice sorgente? Che cos'è un linguaggio di programmazione?

Le macchine non hanno bisogno del codice sorgente. Sono felici in esecuzione di assemblaggio. I linguaggi di programmazione sono a nostro vantaggio. Non vogliamo scrivere assembly. Dobbiamo capire cosa stiamo scrivendo. La programmazione riguarda la scrittura di codice.

Dovresti essere in grado di leggere ciò che scrivi?

Il codice sorgente non è scritto in linguaggio umano. È stato provato (ad esempio FORTRAN) ma non ha completamente successo.

Il codice sorgente non può avere ambiguità. Ecco perché dobbiamo mettere più struttura al suo interno rispetto al testo. Il testo funziona solo con il contesto, che diamo per scontato quando usiamo il testo. Il contesto nel codice sorgente è sempre esploso. Pensa " usando " in C #.

La maggior parte dei linguaggi di programmazione ha ridondanza in modo che il compilatore possa catturarci quando non siamo coerenti. Altre lingue usano più inferenza e cercano di eliminare quella ridondanza.

Nomi di tipo, nomi di metodi e nomi di variabili non sono necessari per i computer. Sono usati da noi per fare riferimento. Il compilatore non capisce la semantica, che è per noi da usare.

I linguaggi di programmazione sono un ponte linguistico tra uomo e macchina. Deve essere scrivibile per noi e leggibile per loro. Le richieste secondarie sono che dovrebbe essere leggibile per noi. Se siamo bravi in ??semantica dove consentito e bravi a strutturare il codice, il codice sorgente dovrebbe essere facile da leggere anche per noi. Il miglior codice non ha bisogno di commenti.

Ma la complessità si nasconde in ogni progetto, devi sempre decidere dove mettere la complessità e quali cammelli ingoiare. Questi sono i luoghi in cui utilizzare i commenti.

Il codice auto-documentato è una facile rinuncia al problema, che nel tempo divergono codice, commento e documentazione. Ed è un fattore disciplinante scrivere un codice chiaro (se sei così severo con te stesso).

Per me, queste sono le regole che cerco di seguire:

Il codice dovrebbe essere semplice e chiaro leggi il più possibile.
I commenti dovrebbero motivare decisioni di progettazione che ho preso, tipo: perché posso usare questo algoritmo o limitazioni del codice, come: non funziona quando ... (dovrebbe essere gestito in un contratto / asserzione in il codice) (solitamente all'interno della funzione / procedura).
La documentazione dovrebbe elencare l'utilizzo (chiamando le convenzioni), lato effetti, possibili valori di ritorno. esso può essere estratto dal codice usando strumenti come jDoc o xmlDoc. esso quindi di solito è al di fuori del funzione / procedura, ma vicino al codice che descrive.

Ciò significa che tutti e tre i mezzi per documentare il codice vivono vicini e quindi hanno maggiori probabilità di essere modificati quando il codice cambia, ma non si sovrappongono in ciò che esprimono.

Il vero problema con il cosiddetto codice auto-documentante è che trasmette ciò che effettivamente fa. Mentre alcuni commenti possono aiutare qualcuno a capire meglio il codice (ad es. Passaggi degli algoritmi, ecc.) È in una certa misura ridondante e dubito che convinceresti il ??tuo pari.

Tuttavia, ciò che è veramente importante nella documentazione sono le cose che non sono direttamente evidenti dal codice: intenti sottostanti, ipotesi, impatti, limitazioni, ecc.

Essere in grado di determinare che un codice fa X da una rapida occhiata è molto più facile che essere in grado di determinare che un codice non fa Y. Deve documentare Y ...

Potresti mostrargli un esempio di un codice che sembra buono, è ovvio, ma in realtà non copre tutte le basi dell'input, per esempio, e vedi se lo trova.

Penso che il codice auto-documentante sia un buon sostituto per i commenti. Se hai bisogno di commenti per spiegare come o perché il codice è così com'è, allora hai una funzione o nomi di variabili che dovrebbero essere modificati per essere più esplicativi. Può dipendere dal programmatore se colmare il deficit con un commento o rinominare alcune variabili e funzioni e rifattorizzare il codice.

Tuttavia non può davvero sostituire la tua documentazione, perché la documentazione è ciò che dai agli altri per spiegare come usare il tuo sistema, piuttosto che come fa le cose.

Modifica: io (e probabilmente tutti gli altri) probabilmente dovrei avere la disposizione che un'app Digital Signal Processing (DSP) dovrebbe essere commentata molto bene. Questo principalmente perché le app DSP sono essenzialmente 2 per i loop alimentati con array di valori e aggiunge / moltiplica / etc detti valori ... per cambiare il programma si cambiano i valori in uno degli array ... sono necessari un paio di commenti per dire cosa stai facendo in quel caso;)

Quando ho scritto codice matematico, a volte ho trovato utile scrivere lunghi commenti simili a un saggio, spiegando la matematica, le convenzioni notazionali che il codice usa e come si adatta tutto insieme. Stiamo parlando di centinaia di righe di documentazione, qui.

Cerco di rendere il mio codice il più autocompattante possibile, ma quando torno a lavorarci su dopo alcuni mesi, ho davvero bisogno di leggere la spiegazione per evitare di ricavarne un hash.

Ora, ovviamente, questo tipo di misura estrema non è necessaria per la maggior parte dei casi. Penso che la morale della storia sia: codice diverso richiede quantità diverse di documentazione. Un po 'di codice può essere scritto in modo così chiaro che non ha bisogno di commenti, quindi scrivilo chiaramente e non usare commenti lì!

Ma un sacco di codice ha bisogno di commenti per avere un senso, quindi scrivilo il più chiaramente possibile e quindi usa tutti i commenti di cui ha bisogno ...

Direi - come molti di voi - che per essere veramente auto-documentante, il codice deve mostrare una qualche forma di intento. Ma sono sorpreso che nessuno abbia ancora menzionato BDD - Behavior Driven Development . Parte dell'idea è che hai dei test automatici (codice) che spiegano l'intento del tuo codice, il che è così difficile da rendere evidente altrimenti.

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software

Un paio di ragioni per cui commenti extra oltre al codice potrebbero essere più chiari:

Il codice che stai guardando è stato generato automaticamente, quindi eventuali modifiche al codice potrebbero essere bloccate la prossima volta che il progetto viene compilato
Un'implementazione tutt'altro che semplice è stata scambiata per un guadagno in termini di prestazioni (srotolamento di un ciclo, creazione di una tabella di ricerca per un calcolo costoso, ecc.)

Sarà tutto in ciò che il team apprezza nella sua documentazione. Suggerirei di documentare il perché / l'intento invece di quanto sia importante e questo non viene sempre catturato nel codice di auto-documentazione. ottenere / impostare no questi sono ovvi - ma calcolo, recupero ecc. qualcosa del perché dovrebbe essere espresso.

Inoltre, fai attenzione alle differenze nella tua squadra se provieni da nazionalità diverse. Le differenze nella dizione possono insinuarsi nella denominazione dei metodi:

BisectionSearch

BinarySearch

BinaryChop

Questi tre metodi hanno contribuito con gli sviluppatori addestrati in 3 diversi continenti a fare la stessa cosa. Solo leggendo i commenti che descrivono l'algoritmo siamo stati in grado di identificare la duplicazione nella nostra libreria.

Per me leggere il codice che necessita di commenti è come leggere un testo nella lingua che non conosco. Vedo la dichiarazione e non capisco cosa fa o perché - e devo guardare i commenti. Ho letto una frase e devo cercare nel dizionario per capire cosa significa.

Di solito è facile scrivere codice che autocerchi ciò che fa. Per dirti perché lo fanno i commenti sono più adatti, ma anche qui il codice può essere migliore. Se capisci il tuo sistema ad ogni livello di astrazione, dovresti provare a organizzare il tuo codice come

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Dove il nome del metodo riflette le tue intenzioni e il corpo del metodo spiega come raggiungere il tuo obiettivo. Non puoi comunque raccontare l'intero libro nel suo titolo, quindi le principali astrazioni del tuo sistema devono ancora essere documentate, così come algoritmi complessi, contratti con metodi non banali e artefatti.

Se il codice prodotto dal tuo collega è davvero autodocumentato, fortunatamente tu e lui. Se ritieni che il codice dei tuoi colleghi abbia bisogno di commenti, è necessario. Basta aprire il posto più banale in esso, leggerlo una volta e vedere se hai capito tutto o no. Se il codice è auto-documentato, allora dovresti. In caso contrario, fai una domanda al tuo collega dopo averti dato una risposta, chiedi perché quella risposta non è stata precedentemente documentata nei commenti o nel codice. Può affermare che il codice è un auto-documento per una persona intelligente come lui, ma deve comunque rispettare gli altri membri del team - se i tuoi compiti richiedono la comprensione del suo codice e il suo codice non ti spiega tutto ciò che devi capire - deve commenti.

Autorizzato sotto: CC-BY-SA insieme a attribuzione

Non affiliato a StackOverflow