Best practice: dove dovrebbero andare i commenti delle funzioni nel codice C/C++?

Question

Quindi ... Capisco che questo potrebbe essere soggettivo, ma mi piacerebbe qualche opinione su ciò che la migliore pratica per questo è.

Dire che ho la seguente intestazione e cpp del file:

intestazione:

// foo.h 

class foo 
{ 
public: 
    int bar(int in); 
}; 

cpp:

// foo.cpp 

int foo::bar(int in) 
{ 
    // some algorithm here which modifies in and returns the modified value 
} 

Ora dire che ho questa funzione commento:

/* 
    input: an integer as input to algorithm foo 

    output: The result of the algorithm foo on input in 

    remarks: This function solves P = NP 
*/ 

---

Sarebbe migliori prassi quella di inserire questa funzione commento nell'intestazione sopra la dichiarazione di funzione o al di sopra della definizione di funzione nel file cpp? Grazie SO

Answer 1

ho messo commenti che descrivono ciò che la funzione fa nell'intestazione e commenti che descrivono come lo fa nel file cpp.

Answer 2

Tendo ad usare il formato di doxygen come commenti di funzione nel file di intestazione, consentendo ai programmatori che sbirciano per saperne di più.

/** 
* Fills the handler with GIF information 
* 
* @param filename GIF File name to be loaded 
* @return Inited GIF Handler or NULL for error 
*/ 
pGifHandler gifHandlerLoad(const char* filename); 

/** 
* Removes all data used by the GIF handler 
* 
* @param gifHandler GIF Handler to be destroyed 
* @note This also clears palette and bitmap(s) 
*/ 
void gifHandlerDestroy(pGifHandler gifHandler); 

programmatori che vogliono sapere come una certa funzione lo fa di lavoro, dovrebbe sbirciare nel file .cpp che sarebbe commentato come raggiunge il suo obiettivo.

Answer 3

Inserire i commenti di funzione nel file di intestazione. Questo (a parte il manuale) è il primo posto in cui gli utenti della tua classe cercheranno la documentazione. Non si preoccupano dell'implementazione, solo dell'interfaccia.

Answer 4

Personalmente preferirei metterlo sopra l'implementazione. Userei anche lo stile Doxygen dato che fornisce le stesse informazioni ma genera documentazione.

Non ha molta importanza, soprattutto se si procede a creare una documentazione separata con doxygen. Vai con quello che preferisci.

Answer 5

Posizionare i commenti nell'intestazione è una soluzione migliore. Questo perché:

• Quando cercando la documentazione relativa una funzione, l'intestazione è la prima posto per verificare.
• Il file di origine potrebbe non essere disponibile.
• Il file di origine contiene molto più della dichiarazione di funzione e i commenti utili potrebbero annegare.

Answer 6

Io uso Doxygen e uso una breve descrizione di una riga nell'intestazione e una descrizione multi-linea complessa nel file di implementazione. Penso che questo produca file di intestazione più puliti che sono più facili ai miei occhi.

Nota: Se stavi rilasciando questo codice come libreria, le persone potrebbero non voler scavare nell'implementazione. Tuttavia, i file di intestazione sono di solito un gioco leale. In questo caso, inserirò la documentazione dettagliata nell'intestazione.

intestazione:

// foo.h 

class foo 
{ 
public: 
    /**\brief This function solves P = NP */ 
    int bar(int in); 
}; 

cpp:

// foo.cpp 

/** 
\param[in] an integer as input to algorithm foo 

\returns The result of the algorithm foo on input in 
*/ 
int foo::bar(int in) 
{ 
    // some algorithm here which modifies in and returns the modified value 
} 

Answer 7

Mi piace usare le condizioni di PRE/POST. Nessuna delle risposte citate è sbagliata. Proprio quello che preferisci/azienda. Ma le condizioni PRE e POST indicano quali sono le variabili in entrata/in uscita e in che modo vengono utilizzate. Garantisce inoltre che stai seguendo una sorta di linea guida su come invocare la funzione (condizioni pre) e quali sono le uscite dopo questa funzione (condizioni post).

Answer 8

Scopo nell'intestazione, contratto sopra la funzione implementazione, perché è nel corpo della funzione.

Che richiede di recapitare .cpp o di utilizzare uno strumento come doxygen per pubblicare la documentazione.

Vantaggio durante le dipendenze: il miglioramento della documentazione non influisce sulle dipendenze dell'intestazione.

In ogni caso, scegliere uno stile, ed essere coerenti

Answer 9

In generale, i commenti dovrebbero essere considerati in un modo simile al codice di separazione - interfaccia commenti -related (come il tuo esempio) sarebbe andato nell'intestazione, mentre l'implementazione , i commenti correlati a sarebbero più adatti per il file .cpp.

Se qualcuno dovesse includere le proprie classi nei propri programmi, dovrebbe essere in grado di ottenere informazioni sufficienti dal file di intestazione per sapere come utilizzare la classe senza dover irrompere nell'implementazione stessa. I commenti alle intestazioni in eccesso sono probabilmente non necessari e servono solo a mettere a posto le informazioni utili.

Answer 10

La pratica migliore è qualunque sia lo standard per l'organizzazione per la quale il codice è scritto.

Se è solo per me: scopo

funzione e l'uso di nell'intestazione, i dettagli delle funzioni per l'attuazione.

Answer 11

Poiché ho sempre utilizzato Visual Assist X e ho la possibilità di saltare il codice molto facilmente, utilizzo il file di intestazione come indice. Cioè, il file di intestazione contiene solo i dati rilevanti senza commenti addizionali in quanto non aggiungere bloat al file. Se il lettore vuole ulteriori informazioni sulla funzione, può passare al cpp.

Questo naturalmente presuppone che tutte le persone che leggono il tuo codice abbiano lo stesso processo di pensiero, che è falso. È bello avere solo gonfiare in un file però.

Answer 12

È come chiedere quali sono le migliori pratiche per mettere i calzini. Alcuni strumenti hanno maggiori possibilità di funzionare se si mettono insieme dichiarazioni e commenti e questo probabilmente ha più senso per ciò che le persone si aspettano. Ma commentare a caso è inutile. Avere in/out roba in particolare, a meno che tu non abbia uno strumento che usa quello.Qualsiasi programmatore può vedere ciò di cui ha bisogno dalla dichiarazione, e lo stesso vale per la lingua in generale. Niente è più inutile di commenti come // questo è il costruttore.

Piuttosto cercare di mantenere il codice stesso il più semplice possibile con i nomi che abbiano un senso e di un'organizzazione generale per il codice e se c'è qualcosa di strano scrivere un vero e proprio punto su di esso come // Abbiamo dovuto fare questo perché alcuni noi usiamo alcune cose strane // che causano alcune altre cose da interrompere e le chiamate ad esso vengono ottimizzate a volte // quindi non togliere queste chiamate di metodo o l'ottimizzatore ottimizza // alcune altre cose e il intero programma smette di funzionare

Answer 13

In ordine di importanza:

1. Se fa parte di un progetto esistente e vi è uno stile di commento prevalente, utilizzare quello. La coerenza all'interno di una base di codice è più importante delle preferenze dei singoli sviluppatori.

2. Se si tratta di un nuovo progetto, utilizzare Doxygen o simili per documentare il codice. Anche se questo non risponde alla tua domanda dato che puoi usare entrambi gli stili con esso. Eseguilo ogni notte in modo da disporre di una documentazione sorgente consultabile aggiornata.

3. Personalmente, preferisco inserire solo un breve riassunto a una riga delle funzioni in linea e dei membri nei file di intestazione, poiché in caso contrario è più difficile ottenere una breve panoramica della funzionalità della classe quando si sfoglia il file di intestazione. Descrizioni dettagliate che lascio per il file .cpp. Alcuni accessori non commento se il loro scopo è davvero ovvio.

Ho anche un grande cruccio per i commenti pigri, in particolare battute:

esempio Questo commento è uno spreco di spazio e potrebbe anche essere eliminato:

/** Get the width */ 
double getWidth(); 

Questo commento è utile:

/** Get the width in inches excluding any margin. */ 
double getWidth(); 

Answer 14

All'interno della funzione, si può mettere il commento sulla stessa linea, come la parentesi graffa di apertura .

/* what is this function for, and so on. Stuff the caller needs to know. */ 
foo() 
{  // pre-condition 
} 

L'ho visto consigliato come posizione per elencare le pre-condizioni. L'ho provato e l'ho trovato piuttosto angusto, perché tendo a scrivere commenti prolissi. Inoltre, la pre-condizione è qualcosa di cui il chiamante deve essere consapevole e non dovrebbe perdersi all'interno del corpo della funzione.

Altrimenti, cerco sempre di mettere le descrizioni generali della funzione al di fuori di esso, e le spiegazioni del perché è codificato nel modo in cui si trova all'interno della funzione, accanto al codice. Quindi, in generale, è d'accordo con lo stile dei promotori di Doxygen.