Дизайн API: гибкость против. Легкость использования
При написании библиотеки или общедоступного API модуля, который будет использоваться большим количеством другого кода в различных сценариях использования, как лучше всего сбалансировать гибкость с простотой использования? Я считаю, что эти двое часто конфликтуют в этом: чем гибче вы делаете что-то, тем труднее заставить это делать что-то хорошо.
Например, C++ STL использует итераторы, которые, IMHO, ужасно низкоуровневые и неприятные для работы, но взамен они чрезвычайно гибки, позволяя одному и тому же коду работать со всеми типами контейнеров STL. Другим примером является философия дизайна стандартной библиотеки Java с ее небольшими, очень специфическими классами, которые разработаны для максимальной модульности и гибкости, по сравнению со стандартной библиотекой Python, с ее предпочтением более плоской иерархии классов, которая упрощает обработку распространенных вариантов использования. . Как такие вещи должны быть сбалансированы?
Ответы 3
Я думаю, вам нужно учитывать целевую аудиторию библиотеки - если вы пишете библиотеку, которую вполне могут использовать менее опытные разработчики, вы должны подумать, как им помочь. В случае C++ STL, вероятно, большинство разработчиков, которые их используют, не возражают против дополнительных механизмов, потому что они привыкли к ним и гораздо больше ценят гибкость.
Возможно, вы захотите подумать о двух уровнях доступа через ваш API, который имеет уровень, упрощающий работу, и уровень, обеспечивающий больший контроль. Но, возможно, вы захотите сначала посмотреть, как будет развиваться структура, прежде чем переходить к такому варианту.
Мне нравится API библиотеки базовых классов .NET. Дизайн библиотеки больше всего соответствует эти рекомендации.
Читая эти и прилагаемую к ним книгу, я извлек несколько ключевых знаний:
API был разработан с учетом того, что современные редакторы имеют возможности intellisense. Допускаются более длинные имена, потому что вы можете занести в строку табуляции полные имена классов и методов. Это противоречит функциям в стиле C с более короткими запутанными именами, такими как
strnicmp().Использование шаблона «Создать, Установить, Вызов»: всегда использовать конструктор по умолчанию, без конструктора параметров. Предоставьте свойства, которые можно устанавливать в любом порядке, а затем разрешите вызов методов. Использование этого шаблона позволяет объекту находиться в недопустимом состоянии в течение короткого периода времени. (После вызова конструктора, но до того, как были установлены какие-либо свойства) Но это нормально. Вы можете сообщить о неправильном использовании API, выбрасывая исключения. Это делает использование класса более доступным.
Если вы являетесь частью органа по стандартизации, который может принудительно использовать ваши классы для других, вы можете выбрать гибкий и сложный (например, stl).
Для всех остальных, если нет действительно веских причин, простота использования всегда должна быть вашим первым выбором. В противном случае мало кто воспользуется вашим кодом / API. Если кривая обучения использованию чужого кода высока, то большинство людей предпочтут повторно реализовывать только те части, которые им нужны. Обычно это происходит быстрее, и проблемы легче решать.
На мой взгляд, «простота понимания» занимает 2-е место после «Все работает правильно», когда дело касается оценки качества кода.
Таким образом, если добавление гибкости происходит за счет простоты изучения и использования, не добавляйте гибкости, пока не будет ДОКАЗАНО, что такая гибкость необходима.
Однако это, конечно, субъективное мнение: мне ужасны API .NET. Я предпочитаю API функционального стиля с в основном неизменяемыми типами и бесплатными (или статическими) функциями, которые работают с ними. Меньше состояния = меньшее сцепление, меньше проблем с потоками, более простой для чтения код. Но это вопрос мнения.