Czy w językach, w których rozróżnia się pliki „źródłowe” i „nagłówkowe” (głównie C i C ++), lepiej udokumentować funkcje w pliku nagłówkowym:
( sprowadzony z 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);
lub w pliku źródłowym?
(splądrowany z 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)
{
...
Zauważ, że niektóre rzeczy są zdefiniowane tylko w nagłówku, takie jak struktury, makra i static inlinefunkcje. Mówię tylko o rzeczach zadeklarowanych w pliku nagłówkowym i zdefiniowanych w pliku źródłowym.
Oto kilka argumentów, o których mogę myśleć. Skłaniam się ku dokumentacji w pliku źródłowym, więc moje argumenty „Pro-header” mogą być nieco słabe.
Pro-nagłówek:
- Użytkownik nie potrzebuje kodu źródłowego, aby zobaczyć dokumentację.
- Źródło może być niewygodne lub nawet niemożliwe do zdobycia.
- Dzięki temu interfejs i implementacja są bardziej oddalone.
Pro-source:
- To sprawia, że nagłówek jest znacznie krótszy, dając czytelnikowi widok z lotu ptaka na moduł jako całość.
- Paruje dokumentację funkcji z jej implementacją, dzięki czemu łatwiej jest zobaczyć, że funkcja robi to, co mówi.
Odpowiadając, należy uważać na argumenty oparte na tym, co mogą zrobić narzędzia i „nowoczesne IDE”. Przykłady:
- Pro-header: Składanie kodu może ułatwić nawigację w skomentowanych nagłówkach, ukrywając komentarze.
- Pro-source: Cscope „s
Find this global definitioncecha powoduje przejście do pliku źródłowego (gdzie definicja jest) raczej niż plik nagłówka (gdzie deklaracja jest).
Nie mówię, nie rób takich argumentów, ale pamiętaj, że nie wszyscy czują się tak dobrze z narzędziami, z których korzystasz, jak ty.