Посмотрел на днях доклад про проектирование API, он неплох (особенно для джунов), но ничего нового для себя, увы, не узнал. Доклад довольно старый, аж из 2007 вернуть бы его, но рекомендую хотя бы пролистать презентацию: повторение — мать ученья.

Интересно в этом докладе то, что докладчик — автор книги Effective Java, той самой, которую очень любили создатели Kotlin, и откуда пошли многие (в том числе спорные) решения в языке. Забавно, что некоторые API java и Гугла (где работал автор) советам, изложенным в докладе, явно не соответствуют.

UPD (07.06.2025): Деменция берет свое, пересмотрел доклад еще раз. Но хотя бы новые мысли появились.

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

Первая часть доклада — хорошая базовая база про то, как стоит подходить к проектированию внешних API в целом. Большинство советов не потеряли свою актуальность, несмотря на то, что доклад из 2007.

Во второй части начинается Java-специфика, которую при желании можно транслировать на проектирование API в общем. И тут тоже вроде правильные вещи говорятся, но часть этих вопросов (например, иммутабельность по умолчанию) за вас решит язык, а часть — спорные. А ближе к концу так вообще вещи, слишком специфичные для Java. Помнится, я после опыта работы со Scala, я был разочарован некоторыми решениями в Kotlin, которые были взяты из Effective Java (и тут я вспомнил, что уже смотрел этот доклад). Но в целом интересно, что еще и разбираются некоторые ошибки проектирования Java API.