> For the complete documentation index, see [llms.txt](https://97-things-every-x-should-know.gitbook.io/97-things-every-programmer-should-know/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://97-things-every-x-should-know.gitbook.io/97-things-every-programmer-should-know/ru/thing_86.md).

# Удобство?

(В оригинале Convenience Is not an -ility)

О важности проектирования хорошего API уже было сказано очень много. Хороший API трудно сделать с первого раза и еще труднее изменить его потом. Большинство программистов выучили, что хороший API соответствует уровням абстракции, демонстрирует логичность и симметрию, а также формирует словарь выразительного языка. Увы, одно знание о принципах не приводит к желаемому результату.

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

* Я не хочу, чтобы другим классам приходилось делать два вызова для того, чтобы сделать вот это.
* Зачем мне нужна еще одна функция, если эта уже делает почти то же самое. Я лучше добавлю туда еще один параметр-переключатель.
* Смотрите, все просто. Если второй параметр заканчивается на .txt, то функция автоматически решит, что первый параметр – это имя файла, и вторую функцию можно не делать.

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

```
parser.processNodes(text, false);
```

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

Сравнение API с языком может привести нас к лучшему пониманию того, какое решение следует принять. API должен предоставить словарь, дающий возможность вышележащему уровню задавать нужные вопросы и получать ответы. Необязательно, чтобы для каждого вопроса использовалось единственное слово. Разнообразие словаря может позволять использовать различия в значениях. Так, мы скорее предпочтем метод run вместо метода walk(true), даже если они будут полностью эквивалентными. Последовательный и хорошо продуманный словарь, используемый для API, сделает код следующего уровня более выразительным и понятным. Еще более важно, что если словарь можно будет комбинировать, то другие программисты смогут использовать API так, как вы и не подозревали – на самом деле отличное удобство для использования. Когда в следующий раз захотите объединить несколько вещей в один метод, вспомните, что в языке нет слов вроде УбратьВКомнатеИСделатьУроки, даже если вам такое слово кажется удобным для обозначения часто используемого действия.

Автор оригинала - [Gregor Hohpe](http://programmer.97things.oreilly.com/wiki/index.php/Gregor_Hohpe)