La scrittura di commenti all'interno di metodi non è una buona pratica? [duplicare]

62

Un amico mi ha detto che scrivere commenti nei 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 nel codice significa che c'è un problema nel codice. Non capisco del tutto il suo ragionamento. Penso che scrivere commenti nel corpo del metodo sia buono e aiuta altri sviluppatori a capirlo meglio e più velocemente. Si prega di fornire i vostri commenti.

    
posta Srini Kandula 28.02.2011 - 02:16
fonte

24 risposte

150

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

    
risposta data 28.02.2011 - 02:18
fonte
88

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 e quindi è facile che i commenti non siano sincronizzati con quello che sta effettivamente accadendo.

Tendo a usare un blocco di commenti per spiegare un particolare logico particolarmente complicato, che altrimenti richiederebbe un po 'di torsione del cervello da leggere. E poi proverò a rendere la logica più chiara e rimuovere la necessità di una spiegazione.

    
risposta data 28.02.2011 - 02:18
fonte
44

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

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

    
risposta data 28.02.2011 - 02:19
fonte
24

Sono sorpreso di quante persone non sono d'accordo con questo punto di vista.

  1. Un buon codice dovrebbe essere auto-documentante, quindi dovresti scegliere con attenzione i nomi dei metodi, i nomi delle variabili, ecc.
  2. Il tuo metodo non dovrebbe essere così lungo da non poter vedere l'intero metodo e i commenti in un'unica schermata

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

Una tipica situazione 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 secondo momento al programmatore. È un buon punto per aggiungere un commento.

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

    
risposta data 28.02.2011 - 02:29
fonte
18

Penso che stia parlando di un caso come questo:

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

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

public void upload() {
    String destinationHost = ....
}
    
risposta data 28.02.2011 - 02:25
fonte
16

Credo che il tuo amico si riferisca a "Clean Code" di Robert C. Martin. Tuttavia, penso che stia semplificando eccessivamente la situazione. Il libro parla di dare ai metodi nomi chiari e descrittivi, che tutti dovremmo sapere, ma che non possono mai essere ripetuti abbastanza. Il libro consiglia inoltre di rendere i metodi molto piccoli avvolgendo qualsiasi blocco di codice che possa essere fornito con 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 5 righe e se hanno tutti un buon nome descrittivo, dovrebbe essere ovvio cosa fanno senza doverli spiegare in un commento.

Tuttavia, ciò non significa che non si dovrebbero mai inserire commenti nei propri metodi. Il punto è che i commenti non dovrebbero 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 volere un commento che spieghi perché hai scelto un algoritmo rispetto a un altro o perché hai scelto una struttura dati rispetto a 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 consiglia di rielaborare il codice errato invece di commentarlo. Questa è certamente una grande idea in teoria, ma in realtà non si può avere il tempo o l'infrastruttura, come una struttura di test dell'unità operativa con l'insieme appropriato di test unitari 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.

    
risposta data 28.02.2011 - 04:05
fonte
8

Sì, sicuramente scrivi commenti nei metodi in Java.

Poiché convenzione del codice di Sun dice:

Java programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are those found in C++, which are delimited by /*...*/, and //. Documentation comments (known as "doc comments") are Java-only, and are delimited by /**...*/. Doc comments can be extracted to HTML files using the javadoc tool.

Quindi, i commenti nei metodi sono commenti di implementazione.

    
risposta data 28.02.2011 - 02:20
fonte
6

Non sono assolutamente d'accordo con il tuo amico e sostengo che i commenti alla funzione inline sono una parte molto importante della scrittura di un buon codice. I commenti alle funzioni sono progettati per dare ai clienti del codice una migliore comprensione di cosa il codice dovrebbe fare - quali sono i suoi parametri e valori di ritorno, i tipi di invarianti che si aspetta di avere in entrata e in uscita, ecc. I 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. Rendono possibile osservare un metodo complesso che un'altra persona ha letto e intuire ciò che l'autore originale stava pensando. Inoltre facilitano la diagnosi dei bug, poiché se i commenti descrivono l'intenzione del codice e le ipotesi che 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 provare a me stesso che il codice che sto per scrivere funzionerà correttamente. Spesso, proverò a non scrivere alcun codice senza prima commentare chiaramente quale sia l'intenzione e come funzionerà. Più volte, questo mi impedisce di commettere errori stupidi nel codice perché scoprirò che la mia spiegazione è errata o che non tiene conto di alcuni casi marginali.

Naturalmente, ognuno di noi ha una propria disciplina di codifica e forse alcune persone trovano più facile scrivere codice senza commenti inline 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 e sono estremamente utili per le altre persone che devono controllare e mantenere il mio codice molto tempo dopo che sono passato a un altro progetto.

    
risposta data 28.02.2011 - 02:21
fonte
6

È probabile che il tuo amico esprima l'idea che i commenti sono, se non sono un "odore di codice", un " deodorante ". Questo non è specifico per i commenti in-method, ma potrebbe essere più vero dei commenti in-method che dei commenti di preambolo.

Quando scrivi un commento, in genere è per spiegare qualcosa. Quando qualcosa ha bisogno di spiegazioni - beh, non è auto-esplicativo. Il grande codice è autoesplicativo. Quindi quando aggiungi commenti, stai coprendo il suo fallimento per auto-spiegarti, senza renderlo auto-esplicativo. Quindi ogni volta che scrivi un commento del genere, invece di cambiando il codice - rinominando, mediante l'estrazione del metodo, ecc. - per rendere è auto-esplicativo, sei a corto di ideali.

Ma a tutti noi manca sempre la perfezione. Ed è spesso meglio aggiungere un commento esplicativo piuttosto che lasciare codice non comprensibile.

    
risposta data 28.02.2011 - 06:14
fonte
2

Quando commenta il tuo codice (o il codice veramente mal documentato di qualcun altro) potresti spesso trovarti di fronte a sentimenti di disgusto , odio o wrath . Il codice può comportarsi in modi frustranti e inaspettati e potresti dover aggiungere alcuni hack molto malvagi per farlo funzionare per un po 'di tempo.

In tutti quei casi che esprimono i tuoi sentimenti annotando le rispettive porzioni di codice con alcune parolacce (vedi il linux kernel fuckcount ) è una pratica comune. Questi 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é alcun altro soggetto agnostico di codice sorgente lo vedranno mai.

I tuoi colleghi programmatori sentiranno comunque sollievo e felicità quando studieranno la fonte. (E naturalmente puoi aggiungere note a te stesso o usare 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 lì in primo luogo, o che dovrebbero essere rimossi prima del rilascio finale, ma in questi giorni 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 leggere (e scrivere) tra le righe .

    
risposta data 28.02.2011 - 15:36
fonte
2

Buoni commenti spiegano il perché non il come. Questa è la distinzione chiave qui. La maggior parte delle persone sarà in grado di seguire ciò che stai facendo, ma perché lo hai fatto richiede commenti extra. Questi commenti dovrebbero essere il più vicino possibile all'operazione.

    
risposta data 28.02.2011 - 16:03
fonte
1

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

Per consigliare positivamente i tuoi amici, tieni presente che possiamo evitare di commentare troppo nominando le variabili e i metodi in modo appropriato e mantenere ogni metodo di piccole dimensioni e accertarci che non facciano troppo personale.

    
risposta data 28.02.2011 - 02:24
fonte
1

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

Non mi associo necessariamente a questa convinzione fino ai suoi estremi (per vari motivi, tra cui la lettura di tale codice può diventare un incubo), ma se uno lo facesse, potrebbe seguire che avrebbero solo un commento per funzione, in quanto esiste un solo concetto per funzione e un commento per concetto.

In entrambi i casi, uso i commenti ogni volta e ovunque ci sia un codice la cui scelta o comportamento non è immediatamente evidente, spesso a causa di considerazioni sulle prestazioni o matematica esoterica. Quel genere di cose spesso non riguarda immediatamente il consumatore della funzione, quindi direi che è una buona idea nasconderlo dalla documentazione.

    
risposta data 28.02.2011 - 03:14
fonte
1

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

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

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

Pertanto - come regola generale: inserire i commenti nella sorgente java sopra il metodo.

Le eccezioni possono e avverranno. Sono d'accordo: usare metodi brevi, scrivere codice di auto-documentazione. Tuttavia javadoc come strumento incoraggia la duplicazione dei commenti, perché altrimenti sembra così nudo nella documentazione. :)

    
risposta data 28.02.2011 - 07:03
fonte
1

Concordo sul fatto che in un metodo scritto da zero, si potrebbe documentare la sua funzione solo nell'intestazione. Tuttavia.

Trovo che i commenti siano spesso inseriti dove sono stati scoperti bug e una sfumatura sottile è stata ignorata 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 di quaranta caratteri (anche se è usato solo in due punti) quando un nome di variabile più breve con un commento succinto può essere più facilmente digerito e riutilizzato in seguito. Pulito e conciso è il migliore, ma soprattutto è un mezzo di comunicazione per gli altri programmatori, così come lo sono anche le e-mail, le lettere e la poesia. E a questo aggiungo la citazione:

"Ho solo reso questa lettera più lunga perché non ho avuto il tempo di accorciarla."

Blaise Pascal, (1623-1662) Lettres provinciales

    
risposta data 28.02.2011 - 07:42
fonte
1

È bello avere il codice che non ha bisogno di commenti. Quando ottieni, 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 che non fa ciò che ci si aspetta. Apparentemente un databile .net non pensa che una riga che è stata importata sia un nuovo record. Quando inserisci i record dalla tabella non succede nulla. La riga che si sta importando deve prima aver cambiato lo stato. Un semplice commento è tutto ciò che è necessario, quindi quando torno da qui a 6 mesi e penso: "Per cosa diavolo ne ho bisogno?" Lo saprò.

    
risposta data 28.02.2011 - 23:13
fonte
0

I commenti rendono il codice più adatto ai programmatori, ricorda 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 gestibile e qualsiasi altro programmatore che guardi il codice troverà facile capire la logica che hai implementato.

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

Come per esempio il seguente codice è autoesplicativo e non richiede alcun commento per rendere chiara la sua funzione

public String getName(){
    return name;
}

Quando un metodo è di grandi dimensioni, 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 auto-esplicativo, ma se lo guardi dopo sei mesi i commenti che hai aggiunto sei mesi fa aiuteranno sicuramente te o qualsiasi altro programmatore a capire il codice rapidamente.

    
risposta data 28.02.2011 - 09:56
fonte
0

In primo luogo, la tua domanda era specificamente orientata a Java - che influenza in modo significativo la risposta.

La quantità di commenti che è richiesta è strettamente correlata alla lingua in cui stai lavorando.

  • Alcuni linguaggi come Java e C # si prestano molto bene al concetto di codice di auto-documentazione. In questi linguaggi i tuoi sforzi sono meglio spesi rendendo il codice stesso leggibile e descrittivo possibile, e quindi aggiungendo commenti in linea solo per cose che non puoi descrivere in modo nativo all'interno della lingua.

  • Alcune lingue 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 auto-documentante. Lo stesso approccio di base si applica ancora: concentrarsi sull'utilizzo del linguaggio il più possibile, quindi aggiungere commenti per compensare le aree non chiare o confuse.

Nel complesso non puoi abolire il 100% dei commenti, ma il tuo obiettivo dovrebbe essere quello di rimuovere il bisogno dei commenti il più possibile rendendo il codice più descrittivo. I risultati di questi sforzi sono in genere meno codice complessivo e codice meglio organizzato. Indipendentemente dal fatto che siano presenti o meno dei commenti questo significa che il tuo codice sarà molto più gestibile e accessibile - il che è in realtà ciò che i commenti sono destinati a supportare in ogni caso.

    
risposta data 28.02.2011 - 16:23
fonte
0

L'idea che Javadoc (o anche i suggerimenti di 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 che è venuto per primo, il javac o javadoc?

È come chiedere chi è venuto per primo, la mucca o la signora O'Leary

Inoltre, javadoc dovrebbe essere per le persone che implementano la tua classe e le 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 aggiustare qualcosa a causa di un errore peloso con un errore, allora vuoi commentarlo nel tuo metodo.

Ovviamente sta supponendo che il 90% del codice, in effetti, le correzioni dei bug siano tutte negative. Non ho mai letto "Il programmatore pragmatico", ma posso presumere che non stia facendo riferimento a quel libro.

    
risposta data 28.02.2011 - 16:45
fonte
0

Lancerò i miei due centesimi ora che la festa è finita abbastanza bene. Uso i commenti quando sto descrivendo un particolare bit della logica aziendale o quando devo aggiungere qualcosa per coprire un caso limite non pertinente.

Il codice si evolve nel tempo per rendere conto di cose che non erano conosciute in anticipo, e quindi quando applichi un cerotto, invece di presumere che sia noto perché hai messo quel cerotto su, a volte aiuta ad aggiungere un piccolo blocco all'interno del codice che dice "oh, a proposito, ho dovuto risolvere questo problema ed ecco il riferimento del bugtracker in modo da poter seguire la conversazione circostante" e nel mio caso (come uso FogBugz) sarebbe assomiglia a questo:

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

o qualsiasi altra cosa. Quindi il mio punto è che qualcosa che sembra fuori luogo e non è leggibile è probabilmente un buon posto per il documento in linea. La conoscenza raccolta è una cosa bellissima.

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 aziendali nella parte anteriore.

/****************************************************************
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, ed è stato in grado di trovare le parti che necessitavano di un tweaking immediatamente) e poi se qualcuno vuole sapere quali sono le specifiche è possibile leggere il commento dall'alto, e se qualcuno vuole sapere cos'è lo pseudo-codice, è lì e se qualcuno vuole convertire lo pseudo-codice nel codice, allora ci vai. Per me questo è molto più leggibile (nel mio caso) in quanto conserva la richiesta originale (ritagliata dall'e-mail) e consente di ragionare rapidamente sul treno del pensiero senza troppe riflessioni e consente l'uso di facili trasformazioni del pseudo nel codice reale.

E sì, ci sono alcuni commenti in linea che dicono che tali e simili non funzionano come previsto nello pseudo-codice perché il requisito non corrispondeva esattamente ai dati, quindi dovevamo ritoccare i dati. Ma questo è il mio punto. Abbiamo documentato in linea i casi limite e abbiamo lasciato lo pseudo-codice nel codice appropriato per seguire la logica, quindi sapevamo tutti cosa ci si aspettava dai requisiti originali

    
risposta data 28.02.2011 - 18:27
fonte
0

Il problema con i commenti in linea è che devono essere mantenuti insieme al codice (anche vero per commenti funzione / metodo / modulo / classe), ma non in modo altrettanto significativo); Dio sa quanto codice sorgente ci sia 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 codice strongmente ottimizzato o "complicato", insieme a una giustificazione per perché il codice è così ottimizzato o "ingannevole" ("mancavano i requisiti prestazionali X e la profilazione ha mostrato il collo di bottiglia per essere in questa sezione, le ottimizzazioni sottostanti hanno ottenuto un rendimento Y% ");

  • In riferimento a uno standard o un requisito ("DTED 0 post spacing is 30 arc secondi");

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

Prima legge sulla documentazione del codice - non documentare l'ovvio. Corollario della prima legge della documentazione del codice: scrivere codice che sia il più ovvio possibile.

    
risposta data 20.02.2012 - 01:59
fonte
-1

Il tuo amico ha torto.
Il tuo amico è parzialmente corretto in quanto l'UTENTE del tuo metodo dovrebbe solo leggere i commenti della documentazione. Tuttavia, a meno che tu non stia scrivendo un codice pulito e non ambiguo che non avrà MAI bisogno di essere modificato per qualsiasi motivo (questo significa che requisiti e piattaforme non cambieranno mai) quindi i commenti nel corpo sono molto utili.

Quando scrivo codice con un design non chiaro (questo succede, non dovrebbe ma lo fa). Scriverò spesso i commenti della documentazione (cosa dovrebbe fare il metodo), il blocco del metodo (Restituisce 0, restituisce null, lancia NotImplemented - Qualunque cosa sia necessario) e quindi scrive i commenti di implementazione come:

//Get Connection String
//Connect to DB !!-- EXCEPTION --!!
//Build Query and Params.
//Parse Query Results
//Return answer

Questo mi darà un'idea chiara di ciò che deve essere fatto. Darà anche a uno sviluppatore futuro un'idea chiara su cosa stavo cercando di realizzare.

In altre parole, i commenti della documentazione sono per gli utenti, spiegando che cosa si sta facendo. Commenti interni (Commenti del codice) sono per gli sviluppatori, che spiegano come viene eseguito.

    
risposta data 28.02.2011 - 16:59
fonte
-1

Ottima domanda.

La risposta potrebbe essere "dipende".

Se riesci a scomporre una parte non chiara in un metodo o una sua funzione, fallo e altri che devono mantenere il tuo codice sorgeranno e ti chiameranno benedetto. Utilizzare i commenti Javadoc per rendere meno chiari i dettagli. Questo potrebbe essere il punto principale del tuo amico.

Ecco una citazione da un testo di musica comp che non riesco a ricordare (e scuse all'autore):

i++; // increment the counter

Il punto dell'autore nell'esempio è che il commento è superfluo. Se hai preso la programmazione 101, non hai bisogno del commento.

Se stai facendo qualcosa di non palesemente ovvio agli altri (o forse a te stesso da sei settimane a partire da ora), allora commenta con ogni mezzo il non così incredibilmente ovvio.

Ad esempio, comprendi immediatamente

assertFalse("valid status differs", file1.isValid() ^ file2.isValid);

o potresti essere aiutato da questi commenti

// Java XOR operator a^b returns true iff a and b differ.
// If file1 and file2 are both isValid, return false.
// The assertion is that the two versions of isValid should be the same.

Anche se sei superbo con gli operatori booleani e usi XOR regolarmente, i commenti dovrebbero aiutare e velocizzare la tua comprensione.

Oppure considera questo frammento per convertire una stringa in un int, utilizzando un numero n, senza commenti:

...
} else {
  Double d = (Double) n;
  Long l = d.longValue(n); 
  int ans = n.intValue(); 
  if (l.equals ((long) ans)) return ans; 
  throw new ParseException("Field too big to be stored as int");
}

Confronta con codice commentato:

...
} else {
  // n must be a double
  Double d = (Double) n;
  Long l = d.longValue(n); // l contains the sInt as a long
  int ans = n.intValue(); // was it truncated?
  if (l.equals ((long) ans)) return ans; // not truncated -- they were equal as longs
  throw new ParseException("Field too big to be stored as int");
}

Ammetto prontamente che questo ultimo frammento è "pesantemente commentato". Penso che i buoni programmatori codificheranno per aiutare a comunicare e chiarire. Err dalla parte dei commenti liberali. Puoi sempre rimuoverli in seguito.

    
risposta data 28.02.2011 - 17:44
fonte
-4

Commenta quando è necessario, non il più possibile.

    
risposta data 19.02.2012 - 21:34
fonte

Leggi altre domande sui tag