Хороший код легко использовать правильно — и сложно использовать неправильно. Это важно при проектировании API: даже внутреннего.
На ревью кода интерфейсов проверяют логику, покрытие тестами, производительность. Но неудобный интерфейс это технический долг, который будет копиться каждый раз, когда кто-то будет использовать этот код.
Вот на что стоит обращать внимание:
• Понятен ли смысл метода. Название должно говорить само за себя без комментария над функцией и без погружения в реализацию.
Если приходится читать тело метода, чтобы понять что он делает, значит имя плохое.
• Предсказуемо ли поведение. Метод с одинаковыми параметрами должен возвращать одинаковый результат.
Скрытые побочные эффекты и неочевидные состояния — прямой путь к багам, которые воспроизводятся через раз.
• Булевые флаги это тревожный знак. Два булевых параметра подряд — почти всегда признак того, что функция делает слишком много или интерфейс не доработан:
ProcessData(bool flag1, bool flag2);
Явные типы — намерение читается сразу:
ProcessData(ProcessMode mode, ValidationOptions options);
• Исключения или типы результата. Исключения созданы для исключительных ситуаций, а типы результата для ожидаемых ошибок.
Смешивать их = заставлять пользователя угадывать, что пойдёт не так и в каком виде.
• Минимум обязательных параметров. Чем больше параметров нужно передать для базового вызова, тем выше порог входа.
Если для простого случая нужно заполнить пять аргументов, скорее всего интерфейс нуждается в умных значениях по умолчанию или отдельном упрощённом методе.
Удобный интерфейс это уважение к тем, кто будет с ним работать. И к себе через полгода, когда придётся вернуться к этому коду.
📍 Навигация: Вакансии • Задачи • Собесы
🐸 Библиотека шарписта
#il_люминатор