it-swarm.it

Scrivere commenti all'interno dei metodi non è una buona pratica?

Un amico mi ha detto che scrivere commenti all'interno dei metodi non è buono. Ha detto che dovremmo avere commenti solo per le definizioni del metodo (javadocs) ma non all'interno del corpo del metodo. Sembra che abbia letto in un libro che avere commenti all'interno del codice significa che c'è un problema nel codice. Non capisco bene il suo ragionamento. Penso che scrivere commenti all'interno del metodo del metodo sia buono e aiuta altri sviluppatori a capirlo meglio e più velocemente. Si prega di fornire i vostri commenti.

63
Srini Kandula

Il tuo amico ha torto e pochissimi programmatori sarebbero d'accordo con lui. Dovresti scrivere commenti quando e dove ritieni che aiutino a capire meglio.

151
mqp

Ignora il tuo amico. Commenta se necessario. Ma cerca di rendere il tuo codice autoesplicativo, in modo che i commenti non siano necessari. Ricorda che il tuo computer non sta eseguendo commenti, quindi è facile che i commenti non siano sincronizzati con ciò che sta realmente accadendo.

Tendo a usare un blocco di commenti per spiegare un po 'di logica particolarmente complicata, che altrimenti richiederebbe qualche attorcigliamento del cervello per leggere. E poi proverò a rendere più chiara la logica, eliminando la necessità di spiegazioni.

90
Michael Petrotta

Il buon codice è auto-documentante. Un metodo dovrebbe fare esattamente una cosa e quella cosa dovrebbe essere ovvia dal nome del metodo e dalle specifiche dei commenti. Pertanto, la necessità di commenti nel metodo che spieghi la logica suggerisce che il metodo dovrebbe essere suddiviso in singoli metodi di responsabilità.

Ora, per la realtà. Ti trovi di fronte a una complessa base di codice di spaghetti e stai cercando di essere gentile con i manutentori. Non hai il tempo o il mandato per refactoring di 8 milioni di righe di codice, e anche se lo facessi, ci sarebbero sfumature perché tutto è complesso. cosa fai?

44
Mark Peters

Sono sorpreso da quante persone non sono d'accordo con questa opinione.

  1. Il buon codice dovrebbe essere auto-documentante, quindi dovresti scegliere con cura i nomi dei metodi, i nomi delle variabili, ecc
  2. Il tuo metodo non dovrebbe essere così lungo che non puoi vedere l'intero metodo e i commenti in una schermata

Detto questo, ci sono eccezioni. Ma sono eccezioni. E il punto è eccezioni, è che sono pochi in numero. Devi solo spiegare il codice in linea se stai facendo qualcosa di controintuitivo.

Una situazione tipica in cui potresti aver bisogno di commenti nel tuo metodo è quando applichi un hack locale per ottimizzare la velocità, ma che in prima lettura potrebbe dare un altro momento a un altro programmatore. Questo è un buon punto per aggiungere un commento.

Ma in generale: no, non aggiungere commenti nei tuoi metodi.

24
markijbema

Penso che stia parlando di un caso come questo:

public void upload() {
    // destination Host
    String Host = ....
}

Dove puoi migliorare il codice avendo un nome di variabile più esplicito, piuttosto che il commento:

public void upload() {
    String destinationHost = ....
}
18
Douglas

Credo che il tuo amico si riferisca a "Clean Code" di Robert C. Martin. Tuttavia, penso che stia semplificando un po 'la situazione. Il libro parla di dare ai metodi nomi chiari e descrittivi, che dovremmo conoscere tutti, ma che non possono mai essere ripetuti abbastanza. Il libro raccomanda inoltre di rendere i metodi molto piccoli racchiudendo qualsiasi blocco di codice a cui può essere assegnato un nome chiaro e descrittivo in un metodo a sé stante. Quindi, se ritieni che un blocco di codice abbia bisogno di un commento che spieghi cosa fa, allora dovresti renderlo un metodo separato con un nome appropriato. In teoria, se tutti i tuoi metodi sono sotto le 5 righe e se hanno tutti un buon nome descrittivo, dovrebbe essere ovvio cosa fanno senza doverlo spiegare in un commento.

Tuttavia, ciò non significa che non dovresti mai avere commenti all'interno dei tuoi metodi. Il punto è che i commenti non devono essere ridondanti. Dovrebbero aggiungere informazioni. Se hai un metodo che fa esattamente una cosa e quella cosa è ovvia dal suo nome, allora non hai bisogno di un commento che spieghi cosa fa. Tuttavia, ha perfettamente senso avere un commento che spiega perché fa la sua cosa in quel modo particolare. Potresti voler un commento che spieghi perché hai scelto un algoritmo piuttosto che un altro o perché hai scelto una struttura di dati piuttosto che un'altra. In altre parole, vuoi che il codice stesso spieghi come funziona e vuoi che i commenti spieghino i motivi delle tue decisioni di progettazione, i. e. perché le cose vengono fatte in questo modo particolare.

Il libro raccomanda di refactoring del codice errato invece di commentarlo. Questa è certamente una grande idea in teoria, ma in realtà potresti non avere il tempo o l'infrastruttura, come un framework di test di unità di lavoro con il set appropriato di test di unità per farlo. Ci sono momenti in cui ti trovi di fronte a una base di codice disordinata, che devi lavorare ieri, e l'unico modo per andare avanti è cercare di capire i pezzi disordinati e commentarli come un modo per prendere appunti per te stesso.

16
Dima

Sì, sicuramente scrivi commenti all'interno dei metodi in Java.

Come convenzione sul codice di Sun dice:

I programmi Java possono avere due tipi di commenti: commenti sull'implementazione e commenti sulla documentazione. I commenti di implementazione sono quelli trovati in C++, che sono delimitati da /*...*/, e //. I commenti alla documentazione (noti come "commenti doc") sono solo Java e delimitati da /**...*/. I commenti del documento possono essere estratti in file HTML usando lo strumento javadoc.

Quindi, i commenti nei metodi sono commenti di implementazione.

8
zengr

Non sono assolutamente d'accordo con il tuo amico e sostengo che i commenti sulle funzioni in linea siano una parte molto importante della scrittura di un buon codice. I commenti di funzione sono progettati per fornire ai clienti del codice una migliore comprensione di ciò che il codice dovrebbe fare - cosa significano i suoi parametri e valori di ritorno, il tipo di invarianti che si aspetta di avere in entrata e in uscita, ecc. Commenti in linea, tuttavia, sono diretti principalmente ai manutentori del codice e idealmente come una serie di note mentali per l'autore originale del codice. Consentono di esaminare un metodo complesso che un'altra persona ha letto e di intuire ciò che l'autore originale stava pensando. Semplificano anche la diagnosi dei bug, poiché se i commenti descrivono quale sia l'intenzione del codice e quali ipotesi sta facendo, può essere molto più facile capire come un pezzo di codice sia errato quando viene rilevato un malfunzionamento.

Personalmente trovo utili i commenti incorporati perché mi costringono a dimostrare a me stesso che il codice che sto per scrivere funzionerà correttamente. Spesso prenderò l'abitudine di non scrivere alcun codice senza prima commentare chiaramente quale sia l'intenzione e come funzionerà. Più volte, questo mi impedisce di fare errori stupidi nel codice perché scoprirò che la mia spiegazione non è corretta o non tiene conto di alcuni casi Edge.

Naturalmente, ognuno ha la propria disciplina di codifica e forse alcune persone trovano più facile scrivere codice senza commenti incorporati e invece dividere il codice in più metodi più piccoli. Tuttavia, per esperienza ho scoperto che i commenti in linea sono inestimabili durante lo sviluppo e il debug, ed estremamente utili per altre persone che devono controllare e conservare il mio codice molto tempo dopo che sono passato a un altro progetto.

6
templatetypedef

Il tuo amico potrebbe benissimo esprimere l'idea che i commenti sono, se non loro stessi, un "odore di codice", un " deodorante ". Questo non è specifico per i commenti nel metodo, ma può tendere ad essere più vero dei commenti nel metodo che dei commenti del preambolo.

Quando scrivi un commento, in genere serve a spiegare qualcosa. Quando qualcosa deve essere spiegato, beh, non è autoesplicativo. Il grande codice è autoesplicativo. Quindi quando aggiungi commenti, stai nascondendo la sua incapacità di auto-spiegarsi, senza renderlo auto-esplicativo. Quindi ogni volta che scrivi un commento del genere, invece di cambiando il codice - rinominando, estraendo il metodo, ecc. - in rendi autoesplicativo, non sei all'altezza dell'ideale.

Ma cadiamo tutti a corto di perfezione di tanto in tanto. Ed è spesso meglio aggiungere un commento esplicativo piuttosto che lasciare un codice difficile da capire senza documenti.

6
Carl Manaster

I buoni commenti spiegano il perché non il come. Questa è la distinzione chiave qui. Molte persone saranno in grado di seguire ciò che stai facendo, ma perché lo hai fatto richiede ulteriori commenti. Tali commenti dovrebbero essere quanto più vicini possibile all'operazione.

3
Bill Leeper

Quando si commenta il proprio codice (o il codice davvero mal documentato di qualcun altro), si può spesso confrontarsi con sentimenti di puro disgusto , odio o ira . Il codice potrebbe comportarsi in modi frustranti e inaspettati e potrebbe essere necessario aggiungere alcuni hack molto malvagi per farlo funzionare per una scadenza.

In tutti questi casi, esprimere le tue sensazioni annotando le rispettive porzioni di codice con parolacce (vedi il linux kernel fuckcount ) è una pratica comune. Quei commenti devono vivere all'interno dei metodi in modo che non compaiano nell'API auto-documentata, quindi né il tuo capo né i tuoi clienti né qualsiasi altra persona agnostica di codice sorgente lo vedranno mai.

I tuoi colleghi programmatori tuttavia sentiranno grande sollievo e felicità quando studiano la fonte . (E ovviamente puoi aggiungere note a te stesso o utilizzare il codice sorgente come mezzo di comunicazione in una certa misura, #TODO: add more examples here)

Ovviamente si potrebbe obiettare che questo tipo di commenti non dovrebbero essere presenti in primo luogo, o che dovrebbero essere rimossi prima della versione finale, ma oggigiorno i progetti software hanno cicli di rilascio molto brevi e alcuni commenti sono ancora rilevanti molte build notturne in seguito, quindi forse il tuo amico dovrebbe iniziare a imparare a leggere (e scrivere) tra le righe .

2
codecraft

È bello avere un codice che non ha bisogno di commenti. Quando ricevi, salvi ed elimini le cose, abbiamo una buona idea di cosa sta succedendo e non abbiamo bisogno di commenti.

A volte il codice diventa disordinato ed è un candidato per il refactoring, quindi potresti dover commentare nel frattempo.

Oggi ho avuto una riga di codice non fare ciò che è previsto. Apparentemente un datable .net non pensa che una riga importata sia un nuovo record. Quando si inseriscono i record dalla tabella non accade nulla. La riga da importare deve prima cambiare lo stato. È sufficiente un semplice commento, quindi quando torno ad esso tra 6 mesi e penso "Per cosa diavolo ho bisogno?" Lo saprò.

1
JeffO

È prassi comune per i programmatori inserire commenti all'interno dei metodi ogni volta che pensano che non sia chiaro agli altri programmatori cosa stia facendo il codice. Inoltre i programmatori inseriscono talvolta commenti TODO all'interno del metodo. Tuttavia, è vero che se hai troppi commenti all'interno dei metodi, potresti dover fare un passo indietro e pensare se stai facendo cose troppo complicate di quanto dovrebbe essere. In altre parole, probabilmente vorrai evitare di commentare qualcosa di ovvio per gli altri programmatori poiché è più difficile leggere il codice con loro.

Per dare un suggerimento positivo ai tuoi amici, dovresti ricordare che possiamo evitare di commentare troppo nominando variabili e metodi correttamente e mantenendo ogni metodo piccolo e assicurandoci che non facciano troppo personale.

1
knoguchi

Penso che la ragione per cui lo ha detto sia perché crede che le funzioni dovrebbero essere abbastanza brevi da incapsulare solo una singola operazione concettuale.

Non sottoscrivo necessariamente questa convinzione al suo estremo (per vari motivi, incluso il fatto che la lettura di tale codice può diventare un incubo), ma se uno lo facesse, potrebbe seguire che avrebbero un solo commento per funzione, poiché c'è solo un concetto per funzione e un commento per concetto.

In entrambi i casi utilizzo i commenti ogni volta e dovunque sia presente un codice la cui scelta o comportamento non è immediatamente ovvio, spesso a che fare con considerazioni sulle prestazioni o matematica esoterica. Questo genere di cose spesso non riguarda immediatamente il consumatore della funzione, quindi direi che in realtà è una buona idea nasconderlo dalla documentazione.

1
Rei Miyasaka

Credo che il tuo amico stesse parlando di javadoc, che genererà la documentazione dal tuo commento se è al di sopra della dichiarazione del tuo metodo (e decorata con un asterisco extra) come questo:

/**
   get a webpage for a given url 
   @param url: the url to get
   @returns String: the http-source 
*/
public String getWebpage (String url) {
... 

Se inserisci questo commento all'interno del metodo è inutile.

Pertanto - come regola generale: inserisci i commenti in Java sopra il metodo.

Possono verificarsi e si verificano eccezioni. Accetto di: utilizzare metodi brevi, scrivere codice autodocumentativo. Comunque javadoc come strumento incoraggia la duplicazione dei commenti, perché altrimenti sembra così nudo nella documentazione. :)

1
user unknown

Concedo il punto che in un metodo scritto da zero, si potrebbe documentare la sua funzione solo nell'intestazione. Però.

Trovo che spesso vengono inseriti commenti in cui sono stati scoperti bug e si è trascurata una sottile sfumatura anche se il metodo ha una sola responsabilità - che siamo onesti, raramente è il caso nel codice legacy. Inoltre, non vedo alcun motivo per avere un nome di variabile lungo quaranta caratteri (anche se utilizzato solo in due punti) quando un nome di variabile più breve con un commento sintetico può essere digerito e riutilizzato più facilmente in seguito. Pulito e conciso è il migliore, ma soprattutto è un mezzo di comunicazione con gli altri programmatori tanto quanto lo sono anche le e-mail, le lettere e la poesia. E a ciò aggiungo la citazione:

"Ho solo allungato questa lettera perché non ho avuto il tempo di accorciarla."

Blaise Pascal, (1623-1662) Lettres provinciales

1
M. Tibbits

I commenti rendono il codice più semplice da programmare, ricordate che i commenti non verranno eseguiti.

Se dovessi leggere il tuo codice dopo pochi mesi, i commenti renderanno più semplice la lettura del codice.

Renderà il codice mantenibile e qualsiasi altro programmatore che lo guarderà troverà facile comprendere la logica che hai implementato.

Ciò non significa che devi sempre aggiungere commenti anche per un metodo con poche righe di codice.

Come ad esempio il seguente codice è autoesplicativo e non richiede commenti per chiarire la sua funzione

public String getName(){
    return name;
}

Mentre quando un metodo è grande, aggiungi un commento in modo che sia più leggibile ogni volta che un programmatore lo guarda.

Ricorda che durante la codifica potresti pensare che il codice sia autoesplicativo, ma quando puoi guardarlo dopo sei mesi i commenti che hai aggiunto sei mesi fa sicuramente aiuteranno te o qualsiasi altro programmatore a capire rapidamente il codice.

0
Alpine

Il problema con i commenti incorporati è che devono essere mantenuti insieme al codice (vero anche per i commenti a livello di funzione/metodo/modulo/classe, ma non nella misura massima); Dio sa quanto codice sorgente è ancora là fuori dove i commenti non hanno assolutamente nulla a che fare con il codice che documentano più, che IMO è altrettanto cattivo o peggio che non avere alcun commento.

Idealmente, la documentazione in linea dovrebbe essere limitata alle seguenti situazioni:

  • Spiegare il codice che è fortemente ottimizzato o "difficile", insieme a una giustificazione per perché il codice è così fortemente ottimizzato o "ingannevole" ("ci mancava il requisito di prestazioni X e la profilazione ha mostrato il collo di bottiglia in questo sezione; le ottimizzazioni sottostanti hanno ottenuto prestazioni Y% ");

  • Facendo riferimento a uno standard o requisito ("La spaziatura post DTED 0 è di 30 secondi d'arco");

  • Identificare il codice che necessita di ulteriori analisi/sviluppo ("TODO");

Prima legge della documentazione del codice - non documentare l'ovvio. Corollario della prima legge della documentazione del codice: scrivi il codice che è ovvio nella massima misura possibile.

0
John Bode

Innanzitutto, la tua domanda era specificamente orientata a Java, il che influenza in modo significativo la risposta.

La quantità di commenti obbligatorio è fortemente correlata alla lingua in cui stai lavorando.

  • Alcuni linguaggi come Java e C # si prestano molto bene al concetto di codice auto-documentante. In questi linguaggi i tuoi sforzi vengono spesi al meglio per rendere il codice stesso il più leggibile e descrittivo possibile, e quindi aggiungendo commenti in linea solo per cose che non puoi descrivere in modo nativo nella lingua.

  • Alcuni linguaggi come SQL sono più difficili da rendere leggibili. La sintassi, l'ordine di valutazione, l'annidamento e così via possono rendere più difficile la progettazione in modo autocompattante. Si applica ancora lo stesso approccio di base: concentrarsi sull'uso della lingua il più possibile, quindi aggiungere commenti per compensare aree poco chiare o confuse.

Nel complesso non puoi abolire al 100% i commenti, ma il tuo obiettivo dovrebbe essere quello di rimuovere il più possibile bisogno per i commenti rendendo il codice più auto-descrittivo. I risultati di questi sforzi sono generalmente meno codice nel complesso e un codice meglio organizzato. Indipendentemente dal fatto che siano ancora presenti commenti, ciò significa che il tuo codice sarà molto più gestibile e accessibile, il che è in realtà ciò che i commenti sono destinati ad aiutare in ogni aspetto.

0
STW

L'idea che Javadoc (o anche i suggerimenti per il completamento automatico di Delphi) dovrebbe cambiare il modo in cui una persona codifica (oltre ad aggiungere funzionalità per javadoc) è piuttosto assurda.

Chiedi al tuo amico quale è venuto per primo, il javac o il javadoc?

È come chiedere quale è venuto prima, la mucca o la signora O'Leary


Inoltre, javadoc dovrebbe essere per le persone che implementano la tua classe e le tue funzioni, i commenti nel codice sono per le persone che mantengono il tuo codice. Soprattutto con i tuoi metodi privati, nessuno dovrebbe necessariamente guardare il tuo codice per vedere cosa fa. Ecco a cosa servono i documenti. Ma se qualcuno ha bisogno di modificare qualcosa a causa di un peloso per un errore, allora vuoi commentarlo nel tuo metodo.

Sta ovviamente assumendo che il 90% del codice, che in realtà è una correzione dei bug, sono tutti cattivi. Non ho mai letto "Il programmatore pragmatico", ma posso presumere che non si riferisca a quel libro.

0
Peter Turner

Lancerò i miei due centesimi ora che la festa è finita abbastanza bene. Uso i commenti quando descrivo un particolare bit di logica aziendale o quando devo aggiungere qualcosa per coprire un caso Edge imprevisto.

Il codice si evolve nel tempo per tenere conto di cose che non erano conosciute in precedenza, quindi quando si applica un cerotto, invece di supporre che sia noto perché si applica quel cerotto, a volte aiuta aggiungere un piccolo blocco all'interno del codice che dice "oh, a proposito, ho dovuto correggere questo ed ecco il riferimento bugtracker in modo da poter seguire la conversazione circostante" e nel mio caso (mentre uso FogBugz) sarebbe simile a questo :

//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );

o qualunque altra cosa. Quindi il mio punto è che qualcosa che sembra fuori posto e non così leggibile è probabilmente un buon posto per incorporare documenti. La conoscenza raccolta è una cosa meravigliosa.

Ma il mio primo punto era la mia logica aziendale. Ho letteralmente un blocco in una procedura memorizzata che sto per riscrivere questo AM che ha alcune regole di business in primo piano.

/****************************************************************
author  yourstruly
date    2010-11-18
descrip intended use is to blah blah blah
        ended up over actual measured blah blah blah according to blah blah blah
        rules from the customer are:
        If the sum of the blah blah blah is higher than the blah blah blah
        and the blah blah blah contain blah blah blah,
        and the blah blah blah is non-zero,
        recalculate the blah blah blah to fit within the blah blah blah

        Additional rules for us internally: 
        if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)

        rewritten here with (1) traceable statements for the where clauses.
        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is non-zero (9)
        and the blah blah blah is lower than the blah blah blah (4)
        and the edited blah blah blah is higher than the blah blah blah (5)
        then recalculate the blah blah blah (6)
        // See note lower in this document on the math

        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is higher than the blah blah blah (7)
        then set the blah blah blah to zero (8)

        (7) dictates the same as (4) but it's easier to do (7)
****************************************************************/

Sorry for the blah blah blah's but proprietary rules and all that ;)

E all'improvviso vedi che ho dei requisiti (!) Incorporati nel mio codice come commenti e posso fare riferimento ai commenti come /*(1)*/ (cosa che faccio) in modo che sia facilmente rintracciabile per il prossimo dipendente (che era, e fu in grado di trovare immediatamente le parti che avevano bisogno di modifiche) e quindi se qualcuno vuole sapere quale fosse la specifica, può leggere il commento dall'alto e se qualcuno vuole sapere qual è lo pseudo-codice è lì e se qualcuno vuole convertire lo pseudo-codice nel codice, allora ci vai. Per me questo è molto più leggibile (per il mio caso) in quanto preserva la richiesta originale (estratta dall'e-mail) e consente al treno di pensiero di essere rapidamente raccolto senza troppi pensieri, e consente l'uso di facili trasformazioni del pseudo in codice reale.

E sì, ci sono alcuni commenti in linea che affermano che tali e tali non hanno funzionato come previsto nello pseudo-codice perché il requisito non corrispondeva perfettamente ai dati, quindi abbiamo dovuto modificare i dati. Ma questo è il mio punto. Abbiamo documentato in linea i casi Edge e abbiamo lasciato lo pseudo-codice nel codice appropriato per seguire la logica, quindi sapevamo tutti cosa ci si aspettava dai requisiti originali

0
jcolebrand