Come convincere le persone a commentare il loro codice [chiuso]

https://stackoverflow.com/questions/159597

03-07-2019
|

Domanda

Quali sono i buoni argomenti per convincere gli altri a commentare il loro codice?

Ho notato che molti programmatori preferiscono la velocità percepita di scrivere codice senza commenti rispetto a lasciare un po 'di documentazione per se stessi e gli altri. Quando provo a convincerli, riesco a sentire cose cotte a metà come " il nome del metodo / classe dovrebbe dire cosa fa " ecc. Cosa diresti loro per cambiare idea?

Se sei contrario al commento, ti preghiamo di lasciare commenti. Questa dovrebbe essere una risorsa per le persone che cercano di convincere le persone a commentare il codice, non altrimenti. : -)

Altre domande correlate sono: Codice commenti , Commenta il tuo codice e Come desideri i tuoi commenti .

Soluzione

Il modo migliore per convincere una persona è farle capire da soli. Renderli debug di codice ben commentato. Mostrerà loro che aspetto ha un buon commento - i commenti sono inutili a meno che non trasmettano realmente informazioni rilevanti (che di solito è il "perché", perché il codice descrive il "cosa"). Noteranno quanto è facile. Quindi lascia che tornino ad alcuni dei loro vecchi codici. Noteranno quanto è difficile. Non hai solo mostrato loro cosa non fare, ma cosa fare (questo è più importante). Non devi più fare. Inoltre, non devi cercare di convincerli verbalmente. Devono semplicemente capire la necessità di commentare il codice a modo loro. Ciò ovviamente presuppone che il codice che deve essere commentato non sia autoesplicativo.

Altri suggerimenti

Commenta solo il " perché " e non il "che cosa". Finora sono d'accordo, dovrebbe essere chiaro dalla classe o dal metodo o dal nome della variabile cosa fa e per cosa viene usato. Rifattore dove non invece di commentarlo.

Se segui questo approccio, otterrai commenti e otterrai utili commenti. Ai programmatori piace spiegare perché stanno facendo qualcosa.

Mostra loro il proprio codice di 6 mesi fa. Se non riescono a capire e delineare esattamente ciò che fa entro 2-4 minuti, è probabile che il tuo punto sia stato espresso.

La mia opinione:

Non lo farei. Il nome del metodo / classe dovrebbe dire cosa fa. In caso contrario, il metodo o la classe sta provando a fare troppo, o è chiamato male.

Sono un fan di commentare perché, non cosa. Se non è chiaro perché il codice stia usando un approccio piuttosto che un altro, commentalo. Se è necessario aggiungere una variabile di hacking non utilizzata per aggirare un bug del compilatore, commentare il perché. Ma commenti come " // Connetti al database " sono segni di codice errato o politiche errate. Un metodo chiamato ConnectToDatabase () è molto meglio. E se ha " // Determina l'IP del server DB " in esso, forse dovrebbe essere estratto in un metodo chiamato " DetermineDbServerIPAddress () " ;.

Il design può essere documentato, ma i commenti sono generalmente un posto scarso per quel livello di documentazione. Con conoscenza del design e alcuni commenti sul perché, cosa e come dovrebbe essere ovvio. In caso contrario, piuttosto che convincerli a commentare il loro codice, convincili a migliorarlo.

Forse è solo qualcosa che deve essere appreso dall'esperienza; nello specifico, l'esperienza di tornare al tuo codice dopo sei mesi e di cercare di capire a cosa diavolo stavi pensando (o cosa stavi facendo) quando l'hai scritto. Questo certamente mi ha convinto che i commenti non erano una cattiva idea.

Dai loro alcuni (~ 500 righe, minimo) orribili, non commentati, con codice spaghetti per refactoring. Assicurarsi che le variabili non abbiano un nome logico. Spazio bianco opzionale.

E guarda come piacciono !

Troppo duro, ma ottiene due punti in una volta sola.

Scrivi bene il tuo codice.
Commentalo in modo che e altri sappiate cosa significa.

Dovrei sottolineare che questo codice non avrebbe dovuto provenire da loro. I commenti sono davvero utili per comprendere il tuo codice, mesi dopo la fine, ma sono anche quasi essenziali per comprendere parti complesse del codice di altre persone . Devono capire che qualcun altro potrebbe dover capire cosa stanno facendo.

Un'ultima modifica: anche il commento qualità è piuttosto importante. Alcuni sviluppatori hanno un rapporto codice / commento quasi 2: 1 nel loro lavoro, ma ciò non li rende buoni commenti. Puoi avere sorprendentemente pochi commenti nel tuo codice e avere ancora molto senso.

Spiega cosa stai facendo . La qualità del codice dovrebbe fare la maggior parte di questo lavoro per te.
Ancora più importante, spiega perché stai facendo qualcosa ! Ho visto così tanto codice che dice esattamente cosa sta facendo qualcosa senza una vera idea del perché lo sviluppatore (sfortunatamente io la maggior parte delle volte) pensava che fosse una buona idea in primo luogo.

Ricorda loro che leggere il codice può solo dire loro cosa fa il codice , non quello che dovrebbe fare.

Se tu o gli altri sviluppatori non avete letto il codice completo (o codice completo 2 ), ma fermate cosa lo stai facendo e lo leggi.

Una cosa che si distingue è " Una funzione dovrebbe fare solo una cosa e farlo bene " ;. quando una tale funzione prende il nome dall'unica cosa che fa bene quale ulteriore necessità c'è di commentare?

I commenti hanno l'abitudine di non essere sincronizzati con il codice che dovrebbero descrivere. Il risultato può essere peggio che non avere il commento originale in primo luogo. Non solo, ma gli sviluppatori sanno che i commenti possono invecchiare e di cui non ci si può fidare. Quindi leggeranno il codice e discerneranno da soli cosa sta effettivamente facendo! Questo in qualche modo annulla il punto di mettere i commenti lì in primo luogo.

Detto questo, lo stesso può valere per il nome di una funzione, potrebbe essere stato ben chiamato originariamente, ma sono state aggiunte nuove straordinarie operazioni a cui non è accennato nel nome.

Tutti i commenti sembrano separare le righe di codice che uno sviluppatore preferirebbe essere più vicine tra loro in modo che possano vedere di più per ogni schermata. Conosco la mia nuova azione su un pezzo di codice con molti commenti che devo capire. Elimina tutti i commenti. Ora posso vedere fino a che punto è il codice.

Alla fine della giornata, se hai intenzione di passare il tempo a fare le cose giuste il tuo tempo è molto meglio speso a refactoring del codice per garantire che sia auto-descrittivo ragionevolmente come può essere piuttosto che scrivere Commenti. Tale esercizio paga in altri modi come l'identificazione di blocchi di codice comuni.

Vale la pena ricordare anche che molti buoni sviluppatori preferiscono di gran lunga scrivere C #, Java nitidi e puliti, a prescindere dai linguaggi umani molto meno precisi con tutte le ipotesi e le ambiguità che hanno. Vero che la maggior parte delle persone con buon senso saprebbe quanti dettagli sono sufficienti ma i buoni sviluppatori non sono "la maggior parte delle persone". Ecco perché finiamo con commenti come \\ aggiunge aeb e lo memorizziamo in c (ok è troppo estremo ma ottieni il punto).

Chiedere loro di fare qualcosa che odiano fare e che francamente non sono molto bravi (anche se sei convinto che sia la cosa giusta da fare) è semplicemente una battaglia già persa.

Non ti sto prendendo in giro, ma dovresti riformulare la domanda in Come convincere gli altri sviluppatori a lavorare in team?

Seriamente, alcune persone credono che tu possa leggere la loro mente.

Se fai parte di un team agile, il codice è di proprietà collettiva, quindi quando vedi un codice non commentato, scomodo o difficile da leggere, vai avanti e modificalo (refactor) in modo da comprenderlo. Se le persone si lamentano, dì loro perché ed essere in anticipo. Che l'hai trovato incomprensibile e nessuno possiede il codice.

La nostra strategia è quella di avere revisioni sistematiche del codice e di rifiutare il codice che non è adeguatamente documentato (tramite commenti, denominazione e organizzazione delle funzioni appropriate, ecc ...). Se non è chiaro per il revisore, si torna al banco di lavoro, punto.

Direi " ieri ho dovuto leggere parte del tuo codice. Sono stato in grado di capirlo, ma inferiore o uguale a 5 righe di commento ben scelte che spiegano come ha raggiunto i suoi obiettivi mi avrebbero permesso di leggerlo in circa un decimo tempo e quindi avrei potuto preoccuparmi di capire un problema invece. Non sono stupido e non sei più intelligente perché puoi scrivere cose che sono difficili da capire. Al contrario, se non riesci a produrre documentazione + insiemi di codici leggibili, allora sei meno uno sviluppatore. & Quot;

Mi è stato trafitto da molto tempo: se scrivi qualcosa e qualcuno di ragionevole capacità non riesce a capirlo, allora è colpa tua, non colpa sua. Questo vale per la scrittura in linguaggi naturali e per la scrittura in linguaggi di programmazione.

Ci sono state discussioni simili sui commenti. Ecco quello su quali regole le persone seguono quando commentano il codice: Quali sono le tue "rigide regole" di commentare il tuo codice? . Alcune delle risposte hanno anche ottime ragioni per cui vuoi commentare il tuo codice.

Mostra saggezza nel tuo desiderio di commenti e saranno più propensi ad ascoltare.

Meno è di più.

Enfatizza la qualità sulla quantità.

Nel mio team, c'è stata una spinta a commentare tutto in alcune API. Alcuni sviluppatori hanno iniziato a utilizzare uno strumento che generava automaticamente commenti osservando i nomi e le firme del metodo.

Ad esempio:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

Riesci a pensare a un grande spreco di proprietà dello schermo? Riesci a pensare a uno spreco di cicli cerebrali maggiore rispetto alla lettura di commenti che non forniscono nuove informazioni?

Se è evidente dalla firma del metodo, non dirlo! Se riesco a capirlo in pochi secondi, non inserirlo in un commento. Come altri hanno già detto, dimmi perché hai scelto di farlo in questo modo, non cosa hai fatto. Scrivi il tuo codice in modo che sia ovvio ciò che fa.

Dai l'esempio. Gli sviluppatori sono facilmente influenzati quando vedono La Cosa Giusta, quindi vedere pratiche solide in azione può incoraggiarli a fare lo stesso. Inoltre, potresti incoraggiare il tuo gruppo ad adottare metriche di codice che indirizzano la manutenibilità e i commenti del codice. Ad esempio, Analisi del codice produrrà un bug per i metodi senza documentazione di riepilogo.

Gli attuali standard di codifica nel mio attuale posto di lavoro sono di commentare ogni funzione. Regole vuote come questa sono dannose e non dovrebbero mai essere in atto. Ci sono situazioni (e alcune comuni) in cui l'aggiunta di commenti rimuove la leggibilità.

class User {
    getUserName() { /* code here */ }
}

Qual è il punto in cui aggiungere un'intestazione di funzione alla parte di codice sopra? Che cos'altro hai intenzione di dire besdies " ottiene il nome utente " ;. Non è necessario commentare tutto il codice. La mia regola empirica è: saltare i commenti se non si aggiungono informazioni utili che la firma della funzione non fornisce.

I commenti devono essere accurati, scritti a livello di intenti (perché non come) e rari.

Quando scrivo codice tendo a commentare abbastanza pesantemente, ovviamente. Quindi, torno indietro e provo a eliminare il maggior numero possibile di commenti, senza ridurre la comprensibilità del codice. > 80% delle volte che è facile come estrarre un metodo ben definito, questo di solito si traduce in un commento che si limita a duplicare le informazioni nel codice stesso. Oltre a ciò, se c'è una sezione di codice che "necessita" di " un commento cerco modi per semplificarlo o renderlo più chiaro.

Il codice deve essere auto-documentato e con le le giuste tecniche può arrivare abbastanza facilmente al 95%. Generalmente lo considero un errore se rimangono dei commenti sul codice che controllo.

Dipende da quanto potere hai ...

Ho trovato un modo molto efficace per renderlo una parte fissa delle revisioni del codice basate su peer - punti per i commenti. Se ci fosse un'osservazione che il codice è stato commentato male, farei in modo che lo sviluppatore lo commentasse con mia soddisfazione, il che sostanzialmente significava che dovevano descriverne abbastanza del codice per poterlo capire stampandolo e leggendolo. E lo farei anche io.

Sorprendentemente, questo era popolare tra gli sviluppatori, anche se suona dickensiano. Sono successe due cose. Innanzitutto, le persone hanno iniziato a commentare il loro codice. In secondo luogo, il codice mal commentato è diventato un segno del fatto che lo sviluppatore non ha capito bene cosa avevano scritto (altrimenti lo avrebbero descritto).

L'unico vero inconveniente era che i commenti dovevano essere mantenuti aggiornati con il codice quando è stato rivisto per correzioni di errori, ecc. Questo era quasi impossibile da applicare in un vero negozio di sviluppo, ma una volta abbastanza buona pratica è stata incisa di successo naturale.

A proposito, preferisco i commenti nel codice stesso piuttosto che un romanzo di Dostoevsky come una stringa di documenti. Il primo è un utile aiuto per i programmatori successivi. Quest'ultimo è solo un lungo pezzo di testo obsoleto che riempie i documenti e induce in errore tutti.

Fagli usare un'API sconosciuta, ma esegui la programmazione su un computer non connesso a Internet (se riesci a trovarli in questi giorni) in modo che non abbiano accesso alla documentazione dell'API. Questo è effettivamente ciò che stanno costringendo gli altri sviluppatori a fare se stanno cercando di usare il codice dei non documentatori!

Devi anche differenziare due diversi commenti qui:

Commenti API (javadoc o altri tipi simili di documentazione): puoi richiederli a usa il proprio codice in uno scenario limite (condizioni al contorno come oggetti null o stringhe vuote o ...) e vedere se riescono davvero a ricordare cosa fa la loro funzione in questi casi
(Ecco perché sono per un javadoc completo, incluso il valore limite )
Commenti interni (all'interno del codice sorgente): puoi chiedere loro di spiegare qualsiasi funzione che hanno codificato, basta scegliere una funzione con un davvero alto livello di complessità ciclomatica e vederli lottare intorno a tutti i diversi flussi di lavoro di codice e ramificazione delle decisioni;)

Bene, c'è sempre il " se non commentate il vostro codice, troveremo qualcun altro che commenterà il loro " approccio.

Più delicatamente, dì loro che stanno deludendo il team se non documentano e commentano quello che stanno facendo. Il codice NON appartiene all'individuo, a meno che non siano lupi solitari completi. Appartiene alla squadra, al gruppo, che si tratti di un'azienda o di una comunità.

" Scrittura codice " = " Scrittura sequenza di comandi in una lingua speciale " + " Scrivere commenti "

È evidente commentare il codice mentre lo si scrive ! Hai mai commentato un codice che ha già 3 o 4 mesi? (Certo che l'hai fatto, ed era tutto fuorché divertente!)

Se il tuo progetto è già ben documentato, i programmatori che aggiungono nuovo codice possono essere motivati ??a scrivere commenti in modo simile.

@James Curran I Sono d'accordo al 100%! Riesco a leggere il tuo codice e capire cosa hai detto al compilatore di fare; ma ciò non significa che il tuo intento fosse farlo dal compilatore. So di non essere un programmatore abbastanza arrogante da credere che ogni volta che scrivo codice fa esattamente quello che stavo cercando di farlo. Inoltre, trovo spesso che mi aiuti a individuare errori logici nel mio codice esaminandoli dopo averlo scritto e cercando di spiegare cosa intendevo fare per il codice.

Un'idea è sottolineare che ci vuole meno di un minuto per scrivere una o due frasi per classe e meno di mezzo minuto per scrivere una frase per metodo.

Dì loro di documentare le loro funzioni e interfacce con i commenti Javadoc e quindi di eseguire il codice attraverso Doxygen per generare una documentazione HTML interessante per il loro codice. Il fattore di freddezza può essere un buon motivatore a volte.

Uso una tecnica sottile:

Ho impostato il livello di avvisi nel progetto da segnalare come errori. E il nostro server di integrazione continua sta costruendo l'intera soluzione insieme alla documentazione XML su ogni controllo.

Se gli sviluppatori non scrivono i commenti, la compilazione fallisce! E dopo, devono scrivere i commenti, quindi dopo un po 'si sono abituati.

Non è aggressivo in termini di pressione, ma lo trovo un modo carino per correggere il loro comportamento.

Se gli sviluppatori devono prendere parte alle revisioni del codice e sono esposti a buoni commenti, dovrebbero essere in grado di ottenere l'indizio. Se non vedono la pratica come utile, dovrebbero ricevere un feedback dai loro revisori.

In caso contrario (supponendo che tu sia il supervisore / gestore) lo rendono parte della loro valutazione delle prestazioni. Se riesci a misurarlo, puoi valutare in base a esso.

Assicurati che sia un commento RIVEDUTO su cui ottieni un punteggio, poiché gli sviluppatori passivi-aggressivi documenteranno ogni ultima affermazione come un FU non così sottile.

Sono diventato un convinto sostenitore di ciò che chiamo Headrick's Rule , chiamato per un mio collega che ha scoperto che un buon modo per motivare qualcuno a fare qualcosa è renderlo doloroso per loro < em> non per farlo.

Nel tuo caso, chiedi ai tuoi sviluppatori non commentatori di passare un'ora o due a spiegare il loro codice, forse a un "lento" pubblico, forse durante l'ora di pranzo "per evitare lo slittamento del progetto" farà molta strada. Le persone intelligenti, anche testarde, imparano velocemente!

Secondo me (e sto parlando della programmazione .Net qui) se devi inserire un commento non sei riuscito a rendere leggibile il codice. La risposta è di solito refactor!

Tuttavia, se ritieni di dover inserire un commento, dovrebbe sempre essere un " why " tipo di commento e non un commento che spiega cosa fa il codice.

Annotare cosa farà un metodo / classe prima di codificare effettivamente aiuta molto a farlo bene - e lo hai commentato.

Impiega solo bravi ingegneri che assicurano che il loro codice dichiari implicitamente l'intenzione (usando commenti e altro). Chiunque desideri un lavoro dovrà farlo nel modo giusto. Duro, ma giusto, IMHO.

Autorizzato sotto: CC-BY-SA insieme a attribuzione

Non affiliato a StackOverflow