Мне нужно создать API, который позволит разработчикам моего клиента использовать проприетарный модуль C, который будет выпущен в виде библиотеки (подумайте .lib или .so, но не исходный код).
Я хотел бы сделать заголовок максимально удобным для разработчиков (так что мне это не понадобится), следуя передовым методам и предоставляя комментарии с описаниями, примерами, предостережениями и т. Д..
Что еще мне следует учитывать с точки зрения бизнеса, техники и здравого смысла?
Спасибо!
Сам заголовочный файл должен быть чистым и аккуратным и, вероятно, минимальным. Он должен указывать, где можно найти документацию. Вероятно, он не должен включать полные примеры (несмотря на некоторые из моих собственных заголовков, которые это делают). Он должен включать основную информацию об авторских правах и лицензии, а также данные об авторе. Он должен содержать только то, что нужно конечным пользователям - ничего, что нужно только разработчикам. Он должен быть автономным; он должен включать любые другие заголовки, необходимые для его работы (чтобы пользователь мог написать «#include "your-header.h"», и код будет компилироваться чисто, даже если это первый или единственный заголовок, который они включают).
Добавлено: заголовок также должен включать некоторую базовую информацию о версии (номер версии файла и дату модификации и / или номер версии продукта и дату выпуска). Это помогает людям смотреть на две версии программного обеспечения, а успешное программное обеспечение выпускается более одного раза.
Добавлено: Адам попросил меня расширить тему «и ничего, что нужно только разработчикам». Это означает, например, что даже несмотря на то, что внутренние функции могут использовать некоторый тип структуры, если ни один из внешних интерфейсов не использует этот тип структуры, то общедоступный заголовок не должен содержать определение этого типа структуры. Он должен быть в частном заголовке, который не распространяется (или распространяется только с полным исходным кодом). Это не должно загрязнять публичный заголовок. Заманчиво сказать: «Но это всего лишь небольшая часть потраченного впустую пространства», и это правильно, но если каждый будет тратить впустую немного места и времени, тогда общие отходы могут стать дорогостоящими.
Ключевым моментом в общедоступном заголовке является то, что он должен содержать все, что нужно пользователю библиотеки (набор функций), и ничего лишнего.
Один из вариантов - создать документацию API из заголовка, используя (например) Doxygen. Очевидно, вы все равно будете отправлять документы вместе с кодом.
Это дает вам два преимущества:
1) Вы не особо беспокоитесь о том, должно ли что-то быть «в документации» или просто «в комментариях в заголовке», потому что изменить одно так же просто, как изменить другое. Так что все идет в документации.
2) Пользователи с меньшей вероятностью начнут читать ваш файл заголовка, потому что они могут быть достаточно уверены, что все интересующее находится в документации. Но даже если они непоколебимы типа «я не доверяю документам, я читаю код», они все равно видят все, что вы хотите, чтобы они видели.
Обратной стороной автоматически сгенерированных документов API является то, что они могут быть кошмаром для поиска, поэтому, IMO, стоит приложить дополнительные усилия для написания действительно хорошей «вводной» документации. Это может быть или не быть частью сгенерированной документации API, в зависимости от того, что вы предпочитаете. Для небольшого API просто список всех функций в "логическом", а не в алфавитном или исходном порядке, описанных в соответствии с тем, для чего они для, а не с тем, что они делают, может значительно упростить получить доступ к документации API. Под «логическим» я имею в виду сначала перечислить часто используемые функции в том порядке, в котором их будет вызывать клиент, с сгруппированными вместе альтернативами, которые «делают то же самое» (например, send и sendTo для сокетов). Затем перечислите менее часто используемые функции и, наконец, непонятные вещи для опытных пользователей и необычных вариантов использования.
Одна из основных трудностей этого подхода, которая может стать препятствием, заключается в том, что в зависимости от вашей организации у вас может быть группа разработчиков документации, и они могут не иметь возможности редактировать заголовок. В лучшем случае они копируют-редактируют то, что вы сделали, а вы вносите изменения и отправляете их обратно. В худшем случае вся идея останавливается, потому что «только команда документации должна писать документацию для клиентов, и она должна быть в стандартном формате, и мы не можем сделать вывод Doxygen в таком формате».
Что касается того, «что еще вы должны учитывать» - вы уже сказали, что будете следовать лучшим практикам, поэтому сложно добавить много :-)
Пожалуйста, убедитесь, что вы не (повторно) определяете символы, которые могут быть определены где-либо еще. Я имею в виду не только стандартные имена, пожалуйста, перед всеми символами, объявленными / определенными в общедоступных заголовках, укажите конкретную строку и избегайте любых имен, которые кто-то мог бы когда-либо использовать.
Я говорю это после того, как увидел слишком много такого безумия в "профессиональных" общедоступных заголовках:
typedef unsigned short uchar;
Другие люди упоминали о проблемах с документацией, поэтому я буду держаться подальше от них :-P. Во-первых, убедитесь, что у вас есть вменяемые охранники. лично мне нравится:
FILENAME_20081110_H_, в основном имя файла заглавными буквами, затем полная дата, это помогает гарантировать, что оно достаточно уникально, даже если в дереве есть другой заголовок с таким же именем. (Например, вы можете представить себе два config.h, включенные из 2 разных каталогов lib, в которых есть охранники, которые используют CONFIG_H_ или что-то в этом роде, и, таким образом, возникают конфликты. Неважно, что вы выберете, если он, вероятно, будет уникальным .
Кроме того, если есть какая-либо вероятность, что этот заголовок будет использоваться в проекте C ++, заключите свои заголовки в такие блоки:
#ifdef __cplusplus
extern "C" {
#endif
/* your stuff */
#ifdef __cplusplus
}
#endif
Это избавит от некоторых головных болей, связанных с проблемами искажения имен, и избавит их от необходимости оборачивать ими заголовок извне.
Рассмотрите возможность написания отдельной документации. Я думаю, что страницы man / info являются хорошим примером того, какой должна быть документация по API.
Подумайте о размещении документации в Интернете в дополнение к тому, что поставляется, и поместите URL-адрес в заголовок. Это позволит некоторым программистам через несколько лет получить доступ к документам, даже если оригиналы были потеряны.
