Commento prima o dopo il codice pertinente [chiuso]

Oserei commentare inline o prima del codice a cui il commento dovrebbe applicarsi. Il senso dei commenti è quello di ottenere una comprensione di base di ciò che fa il codice, senza la necessità di leggere il codice stesso. Quindi ha molto più senso inserire i commenti prima del codice che descrive.

Microsoft afferma che sarebbe una buona pratica di programmazione iniziare le procedure con un piccolo commento. (Non menzionano i commenti dopo le procedure) MSDN Il collegamento riguarda VisualBasic ma si applica alla maggior parte dei linguaggi di programmazione.

Preferisco che i commenti siano al di sopra del codice a cui si riferiscono, ha più senso dire a una persona che legge il codice su cosa sta succedendo piuttosto che cercare di riferirsi al codice precedente per spiegare che alcune linee di codice disordinate hanno risolto alcuni bug è stato difficile, quindi non toccarlo.

Penso che il codice sia generalmente letto da cima a fondo. Se non altro, la memoria muscolare mi indurrebbe ad associare un commento alla successiva riga di codice sottostante.

In genere il commento dovrebbe essere nella parte superiore della riga che segue lo stesso rientro del lavoro. Ad esempio, i commenti sopra il corpo delle funzioni e un commento di copertina appena sopra l'inizio di un algoritmo critico.

Il motivo è che, quando qualcuno inizia a leggerlo, diventa ovvio che il motivo per cui qualcosa viene fatto in questo modo; dove come la persona non sa fino a che punto si ha bisogno di scorrere per la risposta. Se è in cima, è proprio lì da vedere.

Prova a commentare solo dove realmente necessario; il codice dovrebbe cercare di essere auto-documentato quando possibile.

Detto questo, il posizionamento può dipendere: Se usi una riga separata per il commento, metti prima il codice effettivo. Se lo hai sulla stessa linea, mettilo dopo.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Ma mai:

int i = 0;
// this workaround is required to make the compiler happy

So where do most programmers/scripters put a comment: before or after its code?

In molti anni di programmazione usando una varietà di linguaggi, non ricordo di aver visto alcun codice in nessuna lingua in cui un commento è posto su una nuova riga dopo il codice a cui si riferisce. Negli Stati Uniti, almeno, lo standard di fatto sta commentando prima del codice o sulla stessa riga che segue il codice. Scrivi i tuoi commenti dopo il codice relativo invita un test di droga, una valutazione psichiatrica e / o una data con un paio di pinze e una torcia per il taglio.

L'unica eccezione a cui riesco a pensare è un commento che segna la fine di una sezione precedentemente commentata, come questa:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin ha scritto un saggio ben curato sui commenti che vale la pena leggere. Non dice se mette i suoi commenti prima o dopo il codice, ma dice che non li mette mai in linea, e scommetterei un sacco di soldi che non li metterà neanche dopo.

In realtà non sono un grande fan dei commenti. Durante un corso di ingegneria del software, mi è stata presentata l'idea del codice di auto-documentazione. Il codice è l'unica documentazione corretta garantita al 100% di se stesso - i commenti devono essere aggiornati, attentamente costruiti e pertinenti, altrimenti sono trappole che possono essere peggiori di nessun commento. Non è stato fino a quando ho iniziato a lavorare in un negozio C ++ con una guida di stile rigorosa e convenzioni di denominazione significative che ho veramente interiorizzato questo concetto.

A volte i commenti sono necessari. Un sacco di volte, un'attenta denominazione delle variabili, un uso significativo dello spazio bianco e del raggruppamento e una significativa organizzazione logica del codice stesso eliminano la necessità del commento.

Questa è davvero una negazione della finzione e della validità della tua domanda, al contrario di una risposta alla domanda che hai avuto. Continuo a pensare che sia rilevante e possa aiutarti, e non ero un idiota. Altrimenti, i -1 mi domineranno.

Se il commento appare prima che il codice aiuti il lettore a disporre di un contesto per il codice che sta per incontrare. Molto più umano che lanciare loro il codice e spiegare dopo che sono già confusi.

OK, farò il caso "dopo": il codice dovrebbe sempre essere la documentazione primaria, mentre il commento (che non ha alcun significato semantico) è come una spiegazione genetica. Quindi, inserendo il commento sotto il codice che necessita di una spiegazione, il codice diventa la spiegazione principale, e usa solo il commento per chiarimenti. Ad esempio,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Se metti il commento prima del test, il lettore tenderà a leggere il commento come la cosa principale e potrebbe non leggere il codice da vicino, senza rendersi conto di essere stato fuorviato:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Per prendere in prestito alcune idee dalla scrittura tecnica (almeno nella lingua inglese), elementi come note e avvertimenti di avvertimento vengono in genere collocati prima dell'istruzione o della sezione a cui si applica la nota o l'avvertimento cautelativo.

Non vedo perché il codice non possa essere considerato una forma di scrittura tecnica - ogni blocco è un'istruzione. Come la lingua inglese, la maggior parte dei linguaggi di programmazione sono letti da sinistra a destra, dall'alto in basso. I commenti sono note sul codice: potrebbero identificare errori da correggere o cose di cui uno sviluppatore futuro potrebbe essere a conoscenza.

Seguendo questa relazione, sembra più appropriato mettere il commento sopra il blocco di codice a cui si riferisce.

Un commento potrebbe dover passare sopra o sotto un pezzo di codice, a seconda del tipo di commento: se fornisce una spiegazione ultra-breve di ciò che fa il codice, allora deve precedere il codice; se chiarisce dettagliatamente un dettaglio tecnico su come funziona il codice, allora deve seguire il codice.

Fortunatamente, un commento può andare al di sopra o al di sotto di un pezzo di codice, e non lasciare dubbi su quale parte di codice cui appartiene, facendo un uso corretto delle righe vuote. Ovviamente, i programmatori che non prestano attenzione all'uso di righe vuote non sapranno di cosa sto parlando; se sei uno di quelli, salta questa risposta e vai avanti con la tua vita. Ma i programmatori che prestano attenzione alle righe vuote sanno molto bene che le righe vuote vengono utilizzate per dividere il codice in entità logiche. Quindi, se vedi quanto segue:

[blank line]
/* comment */
{ code }
[blank line]

Sai che il commento appartiene al codice e che ti dice cosa fa il codice. Considerando che, se vedi quanto segue:

[blank line]
{ code }
/* comment */
[blank line]

Ancora una volta sai bene che il commento appartiene a quel codice, ed è un chiarimento su come il codice fa quello che fa.

I commenti sopra sono i migliori.

se devi includere commenti e il tuo codice non è auto-esplicativo, allora preferirei non essere confuso da un blocco di codice, quindi vedere "ahh, questo è quello che doveva fare".

Il codice può (e dovrebbe) essere "auto-documentante", ma se devi leggere e capire ogni riga di codice per capire come funziona un metodo. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Quando ho parlato di questo argomento, ho scoperto che la maggior parte dei sistemi di documentazione leggibili dal computer (Doc XML, Doxygen, Java doc ecc.) si aspettano che il commento venga prima del codice a cui si riferisce - è meglio rimanere compatibili con quello standard .

Sono anche d'accordo con il thread SO - Dovremmo aggiungere commenti dopo i blocchi di codice, piuttosto che prima? ..

I'd also rather know up front...

Spesso converto commenti (miei e scritti da altri) in istruzioni di log a livello di traccia. Questo in genere rende molto più facile capire dove metterlo.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Un ulteriore vantaggio è che quando si fa duro, posso attivare la traccia del registro e ottenere un registro di esecuzione più dettagliato.