Commentando codice, intestazione e di origine file C

Question

Sto cercando una "best practice" per documentare il mio codice C. Come in ogni progetto Ho alcuni file di intestazione ".h" e il rispettivo file sorgente ".c"

Nel file di intestazione che tipo di commento si mette in? E nei file sorgente? La domanda sorge perché dal momento che ho commentato bene i miei file di intestazione, i file c sembra un disastro.

Qual è la tua migliori prassi, nel rispetto del codice ben commentato?

Answer 1

L'intestazione è pensato per gli utenti del codice. Quindi qui documento l'interfaccia : come usarla, precondizioni e postcondizioni, eccetera.

Il file .c è per i maintainer . Lì documenta l'implementazione : come funzionano le cose internamente e perché funzionano in questo modo.

Answer 2

Se si tratta di un progetto personale, suggerirei che ci sono un sacco di coding standards che è possibile adottare (quasi tutte includono sezioni su come disporre i commenti).

In caso contrario, mi immagino la vostra azienda/teaam/progetto è già qualcosa in atto in modo da utilizzare quello.

Answer 3

suggerisco di adottare le convenzioni imposte dalla uno strumento come Doxygen. Quindi, invece dei soli commenti al codice, è anche possibile generare documentazione HTML/PDF/Latex ecc. E offre buone convenzioni.

d'accordo con Thomas sui file cpp

Answer 4

Per i file di origine Vi suggerisco di creare un modello di commento per File di intestazione e l'intestazione di funzione.

In caso di commenti alle intestazioni di file, è necessario avere una breve descrizione del file, nomi di funzioni, autore, data di creazione e cronologia per registrare le modifiche.

In caso di intestazione della funzione, è possibile spiegare la logica e lo scopo della funzione e vari parametri. Assicurati che qualsiasi logica complessa o deviazione dal comportamento comune sia ben documentata attraverso i commenti.