Что лучше всего подходит для C++ Public API?

Question

Что лучше всего подходит для открытого API C++?

Я работаю над проектом C++, который имеет несколько пространств имен, каждый с несколькими объектами. Некоторые объекты имеют одинаковые имена, но находятся в разных пространствах имен. В настоящее время каждый объект имеет свой собственный .cpp-файл и .h-файл. Я не уверен, как это сказать ... Было бы целесообразным создать второй файл .h, чтобы открыть только публичный API? Должны ли они быть .h-файлом для пространства имен или для объекта или какой-либо другой области? Что может быть лучшей практикой для создания публичных API для библиотек C++?

Спасибо за любую помощь, Chenz

Answer 1

Иногда удобно иметь один класс во всех файлах .cpp и .h и иметь иерархию пространства имен в качестве иерархии каталогов.
Например, если у вас есть этот класс:

namespace stuff { 
    namespace important { 
    class SecretPassword 
    { 
     ... 
    }; 
    } 
} 

, то он будет в двух файлах:

/stuff/important/SecretPassword.cpp 
/stuff/important/SecretPassword.h 

другой возможный макет может быть:

/src/stuff/important/SecretPassword.cpp 
/include/stuff/important/SecretPassword.h 

Answer 2

Я бы сказал, что это лучше всего решать вам, и тип «библиотеки» это.

Ваш API предоставляет одно «действие»? или обрабатывает только один абстрактный «Тип данных»? примерами для этого были бы zlib и libpng. Оба имеют только один заголовок, который дает все, что необходимо для выполнения функций библиотек.

Если ваша библиотека представляет собой коллекцию несвязанных (или даже связанных) классов, которые делают или нет, та же самая цель, то предоставляйте каждому подмножеству свой собственный заголовок. Основным примером этого будет повышение.

Answer 3

Большой отклик LiraNuna.

Предоставляете ли вы API для приложения или библиотеки?

API-интерфейс приложения обычно предоставляет только методы, которые либо запрашивают состояние приложения, либо пытаются изменить это состояние. В этом случае у вас обычно есть отдельные объявления интерфейса в отдельном файле заголовка. Затем ваши объекты будут реализовывать этот интерфейс для обработки запросов API.

Библиотека, как правило, раскрывает объекты, которые могут быть повторно использованы. В этом случае, вообще говоря, ваш API - это просто общедоступные методы в файле заголовка.

Answer 4

G'day,

Одно предложение взглянуть на С ++ идиомы Handle-Body, иногда известный как Чеширский кот. Вот James Coplien's original paper, содержащий идиому.

Это хорошо известный метод развязки общедоступных API-интерфейсов от реализаций.

НТН

Answer 5

Вот что я привык делать:

«Некоторые объекты имеют одинаковые имена, но находятся в разных пространствах имен»

Вот почему существует пространство имен.

«было бы целесообразно создать второй файл .h выставить только открытый API?»

Вы всегда должны подвергать только открытый API. Но что значит публиковать открытый API? Если бы тогда были только заголовки, поскольку публичный API полагался на частный API, частный API был бы включен публичным API в любом случае. Чтобы публиковать общедоступные API-метки публичных функций/классов с макросом (который в случае Windows экспортирует публичные функции в таблицу символов и, вероятно, вскоре будет принят системами Unix). Поэтому вы должны определить макрос, например MYLIB_API или MYLIB_DECLSPEC, просто проверьте некоторые существующие библиотеки и документацию MS declspec. Достаточно, обычно непубличный API будет храниться в подкаталогах, чтобы он не посещал пользователя библиотеки.

«Должны ли они быть файлом .h для пространства имен или для какого-либо объекта или какой-либо другой области?»

Я предпочитаю Java-стиль, один public класс за заголовок. Я обнаружил, что листы, написанные таким образом, намного чище и читабельны, чем те, которые смешивают имена файлов и структуры. Но бывают случаи, когда я торможу это правило, особенно когда дело касается шаблонов. В таких случаях я даю сообщение #warning, чтобы не включать заголовок напрямую и тщательно объяснять в комментариях, что происходит.

Answer 6

Я согласен с тем, что сказал doc - один класс в файле. 99,9% времени!

Также рассмотрите, какие имена файлов использовать. Как правило, плохая идея иметь несколько заголовков с одинаковыми именами в разных каталогах, хотя классы, которые они содержат, вполне могут находиться в разных пространствах имен.

Особенно, если это общедоступный API, вы, вероятно, не можете контролировать то, что включает в себя пути, определенные пользователем вашей библиотеки, поэтому сборка может оказаться неправильной. Тонкая настройка включенных дорожек определенно не быть решением, которое я бы рекомендовал!

Мы используем соглашение об именах Namespace-Class.h, чтобы явно идентифицировать классы в файлах.