Дизайн API: Гибкость Vs. Простота в использовании

Question

При написании библиотеки или общедоступного API модуля, который будет использоваться многими другими кодами в различных случаях использования, каков наилучший способ сбалансировать гибкость с простотой использования? Я считаю, что в этом часто возникают противоречия: чем гибче вы делаете что-то, тем труднее заставить его делать что-то одно хорошо.

Например, в C ++ STL используются итераторы, которые, на мой взгляд, ужасно низкоуровневые и раздражающие в работе, но взамен они чрезвычайно гибки, позволяя одному и тому же коду работать со всеми видами контейнеров STL. Другим примером является философия проектирования стандартной библиотеки Java с ее небольшими, очень специфическими классами, которые разработаны для максимальной модульности и гибкости, по сравнению со стандартной библиотекой Python, с ее предпочтением более плоской иерархии классов, которая упрощает обработку общих вариантов использования. , Как такие вещи должны быть сбалансированы?

Answer 1

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

Для всех остальных, если нет веских причин, простота использования всегда должна быть вашим первым выбором. В противном случае мало кто будет использовать ваш код / ​​API. Если кривая обучения использованию чужого кода высока, большинство людей предпочтут переопределить только те части, которые им нужны. Обычно это происходит намного быстрее, а проблемы легче решать.

По моему мнению, «легкость понимания» является вторым после «Работает правильно», когда дело доходит до оценки качества кода.

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

Answer 2

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

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

Answer 3

Мне нравится API библиотеки базовых классов .NET. Дизайн библиотеки наиболее соответствует этим рекомендациям.

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

1. API был разработан с учетом того, что современные редакторы имеют возможности intellisense. Длинные имена приемлемы, потому что вы можете табулировать полные имена классов и методов. Это противоречит функциям в стиле C с более короткими запутанными именами, такими как strnicmp()

2. Использование шаблона Create, Set, Call: всегда по умолчанию, без конструктора параметров. Укажите свойства, которые можно установить в любом порядке, а затем разрешите вызов методов. Использование этого шаблона позволяет объекту находиться в недопустимом состоянии в течение короткого периода времени. (После вызова конструктора, но до того, как были установлены какие-либо свойства) Но это нормально. Вы можете сообщить о неправильном использовании API, выбрасывая исключения. Это делает использование класса более доступным.