Professional #include contents

Question

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

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

Что еще следует учитывать из деловых, технических и простых понятий здравого смысла?

Спасибо!

Answer 1

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

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

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

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

Answer 2

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

Answer 3

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

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

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

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

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

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

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

Answer 4

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

Answer 5

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

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

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

#ifdef __cplusplus 
extern "C" { 
#endif 

/* your stuff */ 

#ifdef __cplusplus 
} 
#endif 

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

Answer 6

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

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

typedef unsigned short uchar;