Программа курса Урок 67 из 148 · API, которые невозможно использовать неправильно
API, которые невозможно использовать неправильно

Неправильное использование по замыслу

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

Ассистент, пишущий API, склонен быть услужливым: если вы отправляете до подключения, он подключается за вас; если вы передаёте строку там, где ждали байты, он её кодирует; если вы забыли опцию, есть значение по умолчанию. Каждая такая любезность прячет ошибку, пока она не всплывёт где-то далеко.

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

Четыре инструмента

  • Явные состояния: объект, который знает, новый он, открытый или закрытый, и отклоняет вызовы, которые не подходят.
  • Именованные опции, никаких булевых: mode="dry_run" невозможно случайно перепутать с другим флагом; copy(a, b, True, False) - можно.
  • Никаких тихих значений по умолчанию для выборов, в которых опасно ошибиться: пусть вызывающий скажет сам.
  • Типы, несущие смысл: деньги, знающие свою валюту, нельзя сложить с деньгами в другой.

В этом модуле скрытые скрипты неправильного использования вызывают ваш API неверно и ожидают ошибку на неверном вызове, причём ничего не должно измениться. Скрипты правильного использования ожидают, что всё просто работает. Каждая задача перечисляет виды неправильного использования, от которых надо защититься.

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

Заметили проблему в этом уроке? Сообщите о ней · Спросить об этом уроке

Это упражнение откроется скоро

Закончи предыдущий урок, чтобы открылся этот. Весь курс бесплатный, аккаунт не нужен, и ты можешь прочитать этот урок прямо сейчас.