Commento prima o dopo il codice pertinente [chiuso]

Supponendo che un commento non si adatti (o non possa andare) sulla riga a cui si applica, si dovrebbe scrivere il commento prima del codice o dopo?

Bene, ovunque i futuri lettori capiranno meglio lo scopo del commento. In altre parole, ovunque la maggior parte dei programmatori / programmatori inserisca tali commenti.

Quindi, dove la maggior parte dei programmatori / programmatori inserisce un commento: prima o dopo il suo codice?

Se la tua risposta si applica solo a lingue specifiche, indica quale.

E se puoi citare una specifica o una guida accettata che supporta la tua risposta, tanto meglio.

Vorrei commentare in linea o prima del codice a cui dovrebbe essere applicato il commento. 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 posizionare 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 commenti dopo le procedure) MSDN Il collegamento riguarda VisualBasic ma si applica alla maggior parte dei linguaggi di programmazione che penso.

Preferisco che i commenti siano al di sopra del codice a cui si riferiscono, è più sensato dire a una persona che legge il codice su ciò che sta arrivando piuttosto che provare a fare riferimento al codice precedente per spiegare che alcune linee di codice disordinate hanno risolto alcuni bug che erano difficili quindi non toccarlo.

Penso che il codice sia generalmente letto dall'alto verso il basso. Se non altro, la memoria muscolare mi indurrebbe ad associare un commento alla riga successiva di codice sottostante.

In genere il commento dovrebbe essere all'inizio della riga seguendo la stessa rientranza del lavoro. Ad esempio, commenti sopra il corpo delle funzioni e commenti di copertina appena sopra l'inizio di un algoritmo critico.

Il motivo è che quando qualcuno inizia a leggerlo, diventa ovvia la domanda sul perché qualcosa venga fatto in questo modo; dove come la persona non sa fino a che punto è necessario scorrere per la risposta. Se è in cima, è proprio lì per vedere.

Quindi, dove la maggior parte dei programmatori / programmatori inserisce un commento: prima o dopo il suo codice?

In molti anni di programmazione usando una varietà di linguaggi, non ricordo di aver visto alcun codice in nessuna lingua in cui un commento è inserito in 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. Scrivere i tuoi commenti dopo il codice correlato invita un test antidroga, una valutazione psichiatrica e / o una data con un paio di pinze e una torcia.

L'unica eccezione che mi viene in mente è un commento che segna la fine di una sezione precedentemente commentata, in questo modo:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin ha scritto un saggio ben considerato sui commenti che vale la pena leggere. Non dice se inserisce 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 inserirà neanche dopo.

Prova a commentare solo dove è veramente necessario; il codice dovrebbe cercare di essere auto-documentato ogni volta che è possibile.

Detto questo, il posizionamento può dipendere: se si utilizza una riga separata per il commento, inserirlo prima del 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

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

A volte sono necessari commenti. Molte volte, l'attenta denominazione delle variabili, l'uso significativo dello spazio bianco e del raggruppamento e un'organizzazione logica significativa del codice stesso elimina la necessità del commento.

Questa è davvero una negazione della pretesa e della validità della tua domanda, al contrario di una risposta alla domanda che avevi. Penso ancora che sia pertinente e possa aiutarti, e non ero un idiota. Altrimenti, gli -1 mi domineranno.

Far apparire il commento prima del codice aiuta il lettore ad avere 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 "after": il codice dovrebbe sempre essere la documentazione principale, mentre il commento (che non ha significato semantico) è come una spiegazione tra parentesi. Quindi, inserendo il commento sotto il codice che necessita di spiegazioni, il codice viene lasciato come spiegazione principale e utilizza il commento solo per chiarimenti. Per 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 cosa principale e potrebbe non leggere il codice da vicino, non rendendosi conto che sono stati fuorviati:

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

Per prendere in prestito alcune idee dalla scrittura tecnica (almeno in lingua inglese), cose come note e avvertenze sono generalmente poste prima dell'istruzione o della sezione a cui si applica la nota o avvertenza.

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 vengono letti da sinistra a destra, dall'alto verso il basso. I commenti sono note sul codice: potrebbero identificare errori da correggere o cose di cui un futuro sviluppatore potrebbe aver bisogno.

A seguito di questa relazione, sembra più appropriato inserire il commento sopra il blocco di codice a cui fa riferimento.

Un commento potrebbe dover andare 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 in modo elaborato 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 si riferisca, facendo un uso corretto delle righe vuote. Naturalmente, i programmatori che non prestano attenzione all'uso delle righe vuote non sapranno di cosa sto parlando; se sei uno di quelli, per favore salta questa risposta e vai avanti con la tua vita. Ma i programmatori che prestano attenzione alle righe vuote sanno benissimo 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 benissimo 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 è autoesplicativo, allora preferirei non essere confuso da un blocco di codice, quindi vedere "ahh, è quello che doveva fare".

Il codice può (e dovrebbe) essere "auto-documentazione", ma se devi leggere e comprendere 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 goggled su questo argomento, ho scoperto che la maggior parte dei sistemi di documentazione leggibili da 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? ..

Preferirei anche sapere in anticipo ...

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

    // 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 diventa difficile posso attivare la traccia del registro e ottenere un registro di esecuzione più dettagliato.