19/97: Удобство - это не -илити

Это перевод Convenience Is not an -ility. Автор: Gregor Hohpe.

Из "97-ми вещей, которые должен знать каждый программист".

(прим.пер.: видимо, в заголовке имеются ввиду слова типа "юзабилити" и т.п.)

Много всего было сказано о важности и проблемах проектирования хорошего API. Сложно сделать всё верно с первого раза и ещё более сложно потом его изменить. Чем-то это похоже на воспитание детей. Большинство программистов выучили, что хороший API соответствует уровням абстракции, демонстрирует логичность и симметрию, а также формирует словарь выразительного языка. Увы, одно знание лишь о принципах не приводит к желаемому результату. К сладкому привыкать вредно.

Вместо чтения возвышенных проповедей я хочу лишь обратить внимание на одну "стратегию" проектирования API, с которой я встречаюсь снова и снова – аргумент удобства. Обычно всё начинается с "просветления" вроде:

• Я не хочу, чтобы другим классам приходилось делать два вызова, чтобы сделать одну вещь.
• Зачем мне создавать ещё один метод, если он делает почти то же самое, что и вон тот? Я просто добавлю ещё одну опцию.
• Видишь, всё просто: если второй строковый параметр оканчивается на '.txt', то метод автоматически предполагает, что первый параметр - это имя файла. Так что мне не надо два разных метода.

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

Parser.ProcessNodes(Text, False);

практически не имеет смысла, если вы не знаете реализацию метода или хотя бы не заглянете в документацию. Этот способ проектирования API делает проще жизнь реализатора API - ему меньше писать. Сравните это с удобством вызова для использующего API. Ничего радикально неправильного в удобстве нет, если говорить об удобстве как о противоядии к монотонности, неуклюжести или неповоротливости. Однако, если чуть глубже копнуть, то противоядием к перечисленным симптомам будет эффективность, логичность и элегантность, а вовсе не удобство. API предназначен для скрытия нижележащей сложности, и вполне логично ожидать, что проектирование хорошего API потребует определенных усилий. Написать один большой метод будет гораздо удобнее, чем продумать адекватный набор операций, но вот будет ли этот метод более удобен в использовании?

Сравнение API с языком может привести нас к лучшему пониманию того, какое решение следует принять. API должен предоставить словарь, дающий возможность вышележащему уровню задавать нужные вопросы и получать ответы. Необязательно, чтобы для каждого вопроса использовалось единственное слово. Разнообразие словаря может позволять использовать различия в значениях. Так, мы скорее предпочтем метод Run вместо метода Walk(True), даже если они будут полностью эквивалентными. Последовательный и хорошо продуманный словарь, используемый для API, сделает код следующего уровня более выразительным и понятным. Еще более важно, что если словарь можно будет комбинировать, то другие программисты смогут использовать API так, как вы и не подозревали – на самом деле отличное удобство для использования. Когда в следующий раз захотите объединить несколько вещей в один метод, вспомните, что в языке нет слов вроде MakeUpYourRoomBeQuietAndDoYourHomeWork - даже если вам такое слово кажется удобным для обозначения часто используемого действия.