In Sprachen, die zwischen einer "Quell" - und "Header" -Datei (hauptsächlich C und C ++) unterscheiden, ist es besser, Funktionen in der Header-Datei zu dokumentieren:
(gestohlen von CCAN )
/**
* time_now - return the current time
*
* Example:
* printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
*/
struct timeval time_now(void);
oder in der Quelldatei?
(gestohlen von PostgreSQL)
/*
* Convert a UTF-8 character to a Unicode code point.
* This is a one-character version of pg_utf2wchar_with_len.
*
* No error checks here, c must point to a long-enough string.
*/
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...
Beachten Sie, dass einige Dinge nur in der Kopfzeile definiert sind, z. B. Strukturen, Makros und static inlineFunktionen. Ich spreche nur von Dingen, die in einer Header-Datei deklariert und in einer Quelldatei definiert sind .
Hier sind einige Argumente, die mir einfallen. Ich neige dazu, in der Quelldatei zu dokumentieren, daher sind meine Argumente für "Pro-Header" möglicherweise etwas schwach.
Pro-Header:
- Der Benutzer benötigt den Quellcode nicht, um die Dokumentation anzuzeigen.
- Die Quelle kann unbequem oder sogar unmöglich zu beschaffen sein.
- Dies hält die Schnittstelle und die Implementierung weiter auseinander.
Pro-Source:
- Dadurch wird der Header viel kürzer und der Leser kann das Modul als Ganzes aus der Vogelperspektive betrachten.
- Es verbindet die Dokumentation einer Funktion mit ihrer Implementierung, sodass leichter erkennbar ist, dass eine Funktion das tut, was sie sagt.
Seien Sie bei der Beantwortung vorsichtig mit Argumenten, die darauf beruhen, was Tools und "moderne IDEs" können. Beispiele:
- Pro-Header: Durch das Falten des Codes können kommentierte Header besser navigiert werden, indem die Kommentare ausgeblendet werden.
- Pro-Source: Mit der
Find this global definitionFunktion von cscope gelangen Sie zur Quelldatei (wo sich die Definition befindet) und nicht zur Header-Datei (wo sich die Deklaration befindet).
Ich sage nicht, dass Sie solche Argumente nicht vorbringen, aber denken Sie daran, dass nicht jeder mit den von Ihnen verwendeten Tools so vertraut ist wie Sie.