Per riformulare la domanda: quale è meglio, un commento centrale dettagliato o più piccoli "spruzzi"?
Resta con me mentre preparo la scena:
Ho questa funzione per prelevare un valore da un'implementazione di coda:
int queue_pop(queue *list, void **pValue);
Se hai familiarità con C, comprendi che chiamare questa funzione in questo modo:
struct foo *pFoo;
int rc;
rc = queue_pop(g_FooList, &pFoo);
ottieni questo:
gcc: warning-incompatible pointer type passing 'foo **' to parameter of type 'void **'
Ora, come capita, chiamare questa funzione in questo modo è perfettamente sicuro; la funzione non si rivolge mai al puntatore dereferenziato come qualcosa di diverso da un vuoto *, e l'allocazione e la copia della memoria viene eseguita in base rigorosamente alla dimensione dell'elemento, che è definita in ogni coda data. Ma, per evitare gli avvertimenti, lo chiamo in questo modo:
rc = queue_pop(g_FooList, (void**)&pFoo);
che non è strettamente portatile in C, ma anche in questo caso è perfettamente sicuro. Ma poiché gli argomenti della funzione di cast non sono quasi mai necessari in C, ed è in effetti quasi SEMPRE a coprire un errore, documento la prima chiamata di questo tipo in ogni funzione come questa:
/* Explicit cast - see comments on queue_pop function in queue.c */
rc = queue_pop(g_FooList, (void**)&pFoo);
In questo modo, chiunque legga il codice può aprire il file queue.c e leggere una spiegazione dettagliata del perché questo è OK, e non preoccuparsi di ciò. E poiché non lo faranno, almeno sanno che è stato fatto apposta, e c'è una ragione.
La domanda sorge perché somone mi ha suggerito di liberarmi del cast - dal momento che è così insolito - e di chiamare semplicemente la funzione con il tipo di puntatore concreto. Quindi sopprimete l'avviso con una #pragma push nella parte superiore del file sorgente e inserite un commento dettagliato sul pragma che spiega la soppressione. Dato che alla fine il codebase sarà open source e i commenti del codice sorgente (rispetto ai commenti del file di intestazione) avranno quindi un pubblico più ampio del normale, sarà più organizzato in questo modo.
A parte il fatto che non sono un grande fan di sopprimere gli avvertimenti in primo luogo (ad eccezione di alcuni dei più sciatti di MSVC), è stata la mia esperienza che:
- A) le persone non leggeranno
- B) se vuoi che qualcuno legga qualcosa, è meglio che lo attacchi proprio davanti ai loro occhi
- C) vedi A
Ora, il tag comments dice che è per domande su "Best Practices", ma mi rendo conto che questo potrebbe tendere un po 'troppo verso "opiniony". Se è così, appendi solo alcuni downvotes e cancellerò la domanda.
EDIT Ho visto questa domanda , ma sembra un mosh generale sull'opportunità o meno di usare i commenti. Non è questo il problema qui: userò sicuramente una sorta di commento.