Мови, які розрізняють файл "джерело" та "заголовок" (головним чином C та C ++), краще документувати функції у файлі заголовка:
(розкрадений від 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);чи у вихідному файлі?
(викрадено з 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)
{
...Зауважте, що деякі речі визначені лише у заголовку, наприклад, структури, макроси та static inlineфункції. Я говорю лише про речі, які задекларовані у файлі заголовка та визначені у вихідному файлі.
Ось кілька аргументів, які я можу придумати. Я схиляюся до документування у вихідному файлі, тому мої аргументи "заголовок" можуть бути дещо слабкими.
Проголовок:
- Користувачеві не потрібен вихідний код для перегляду документації.
- Джерело може бути незручним або навіть неможливим придбати.
- Це зберігає інтерфейс та реалізацію далі.
Про-джерело:
- Це робить заголовок набагато коротшим, надаючи читачеві огляд модуля в цілому.
- Він поєднує документацію функції з її реалізацією, полегшуючи побачити, що функція робить те, що, як вона каже, робить.
Відповідаючи, будьте уважні до аргументів, виходячи з того, які інструменти та "сучасні ІДЕ" можуть зробити. Приклади:
- Прозаголовок: складання коду може допомогти зробити коментовані заголовки більш зручними, ховаючи коментарі.
- Pro-джерело: Cscope «s
Find this global definitionфункція приймає вас до вихідного файлу (де визначення є) , а не файл заголовка (де декларація є).
Я не кажу, що не варто наводити таких аргументів, але майте на увазі, що не всім так зручно користуватися інструментами, якими ви користуєтесь.