Профессиональное содержание

Question

Мне нужно создать API, который позволит разработчикам моего клиента использовать собственный модуль C, который будет выпущен в виде библиотеки (думаю, .lib или .so - не исходный код).

Я бы хотел сделать заголовок максимально удобным для разработчиков (так что мне это не нужно), следуя рекомендациям и предоставляя комментарии с описаниями, примерами, предостережениями и т. 1007 * Что еще я должен рассмотреть с точки зрения бизнеса, техники и здравого смысла?

Спасибо!

Answer 1

Пожалуйста, пожалуйста, убедитесь, что вы не переопределяете символы, которые могут быть определены где-либо еще. Я имею в виду не только стандартные имена, пожалуйста, перед всеми символами, объявленными / определенными в общедоступных заголовках, ставьте префикс с конкретной строкой и избегайте любых имен, которые кто-либо еще мог бы использовать при использовании.

Я говорю это, увидев слишком много сумасшествия, подобного этому, в «профессиональных» общедоступных заголовках:

typedef unsigned short uchar;

Answer 2

Другие люди упоминали о проблемах с документацией, поэтому я буду держаться подальше от них :-P. Во-первых, убедитесь, что у вас есть вменяемые охранники. лично мне нравятся:

FILENAME_20081110_H_, в основном имя файла во всех заглавных буквах, затем полная дата, это помогает гарантировать, что оно достаточно уникально, даже если в дереве есть другой заголовок с таким же именем. (Например, вы можете представить, что два config.h включены из двух разных каталогов lib, с элементами защиты, которые используют CONFIG_H_ или что-то в этом роде, и, таким образом, имеют конфликт. Неважно, что вы выберете, если только быть уникальным.

Кроме того, если есть любой шанс того, что этот заголовок будет использоваться в проекте c ++, пожалуйста, оберните ваши заголовки в блоки, подобные этому:

#ifdef __cplusplus
extern "C" {
#endif

/* your stuff */

#ifdef __cplusplus
}
#endif

Это избавит от некоторых головных болей с проблемами искажения имен и сделает так, что им не придется оборачивать заголовок внешне этим.

Answer 3

Один из вариантов - сгенерировать документацию API из заголовка, используя, например, Doxygen. Очевидно, вы все равно отправите документы вместе с кодом.

Это дает вам два преимущества:

1) Вы не очень беспокоитесь о том, должно ли что-то быть "в документации" или просто "в комментариях в заголовке", потому что изменить одно так же просто, как и другое. Так что все идет в документации.

2) Пользователи с меньшей вероятностью начнут читать ваш заголовочный файл, потому что они могут быть достаточно уверены, что в документации есть все, что интересует. Но даже если они твердолобые «я не доверяю документам, я читаю код», они все равно видят все, что вы хотите, чтобы они увидели.

Недостаток автоматически генерируемых документов API заключается в том, что их поиск может стать кошмаром для поиска, поэтому IMO стоит приложить дополнительные усилия для написания действительно хорошей "вводной" документации. Это может или не может быть частью сгенерированных документов API, в зависимости от того, что вы предпочитаете. Для небольшого API, просто список всех функций в «логическом», а не в алфавитном или исходном порядке, описанный в соответствии с тем, что они для , а не с тем, что они делают, может значительно облегчить получение в API документы. Под «логическим» я подразумеваю сначала перечислить часто используемые функции в порядке, в котором их вызовет клиент, с альтернативами, которые «делают то же самое» (например, send и sendTo для сокетов), сгруппированными вместе. Затем перечислите редко используемые функции и, наконец, непонятные вещи для опытных пользователей и необычные варианты использования.

Одна из основных трудностей в подходе, который может быть ограничителем показа, состоит в том, что в зависимости от вашей организации у вас может быть команда разработчиков документации, и они могут не иметь возможности редактировать заголовок. В лучшем случае они копируют, редактируют то, что вы сделали, и вы вносите изменения и возвращаете их. В худшем случае вся идея останавливается, потому что «только команда документации должна писать документацию, ориентированную на клиента, и она должна быть в стандартном формате, и мы не можем сделать вывод Doxygen таким форматом».

Что касается «что еще следует учитывать» - вы уже сказали, что будете следовать рекомендациям, поэтому сложно добавить многое: -)

Answer 4

Сам заголовочный файл должен быть чистым и аккуратным и, вероятно, близким к минимальному. Следует указать, где можно найти документацию. Это, вероятно, не должно включать полные примеры (несмотря на некоторые из моих собственных заголовков, которые делают это). Он должен включать основную информацию об авторском праве, лицензии и сведения об авторе. Он должен содержать только то, что нужно конечным пользователям - ничего, что нужно только разработчикам. Это должно быть автономным; он должен включать любые другие заголовки, необходимые для его работы (чтобы пользователь мог написать «#include "your-header.h"», и код будет скомпилирован без ошибок, даже если это первый или единственный заголовок, который он включает).

Добавлено : в заголовке также должна содержаться некоторая базовая информация о версии (номер версии файла и дата изменения, и / или номер версии продукта и дата выпуска). Это помогает людям смотреть на два выпуска программного обеспечения - и успешное программное обеспечение выпускается более одного раза.

Добавлено : Адам попросил меня остановиться на "и ничего, что нужно только разработчикам". Это означает, например, что даже если внутренние функции могут использовать некоторый тип структуры, если ни один из внешних интерфейсов не использует этот тип структуры, тогда открытый заголовок не должен содержать определения этого типа структуры. Он должен быть в частном заголовке, который не распространяется (или распространяется только с полным источником). Он не должен загрязнять публичный заголовок. Соблазнительно сказать «но это только немного потраченного впустую пространства», и это точно, но если каждый потратит немного места и времени, тогда все потери могут стать дорогими.

Ключевым моментом в общедоступном заголовке является то, что он должен содержать все, что нужно пользователю библиотеки (набор функций), и ничего, что ему не нужно.

Answer 5

Рассмотрите возможность написания отдельной документации. Я думаю, что страницы man / info являются хорошим примером того, какими должны быть API-документы.

Answer 6

Подумайте о том, чтобы разместить документы в Интернете, в дополнение к любым судам, и поместить URL-адрес в заголовок. Это позволит программисту по техническому обслуживанию через несколько лет получить доступ к документации, даже если оригиналы были утеряны.