Про именование интерфейсов

[sokolovvs]

Здравствуйте, Адель!
Привожу цитату из книги:

Второй вариант: использование суффикса *Interface, например, создать интерфейс StorageInterface. Таким образом, имея класс Storage реализующий интерфейс StorageInterface, мы постулируем, что у нас есть интерфейс и его «главная» реализация. Все остальные реализации этого интерфейса выглядят вторичными. Само существование интерфейса StorageInterface выглядит искусственным: он был создан, чтобы код удовлетворял каким-то принципам, или просто для юнит-тестирования.

Это явление встречается и в других языках. В C# принят префикс I*. Интерфейс IList и класс List, например. В Java не приняты префиксы и суффиксы, но там часто случается такое:

class StorageImpl implements Storage

https://github.com/adelf/acwa_book_ru/blame/master/manuscript/2-di.md#L362

Вероятно здесь речь именно про то, что имя класса Storage плохое только если он реализует интерфейс с названием StorageInterface, т.к.

мы постулируем, что у нас есть интерфейс и его «главная» реализация

а не про то, что суффикс Interface нельзя или не стоит использовать для именования интерфейсов?
PSR обязывает использовать венгерскую нотацию для именования интерфейсов.

[adelf]

PSR этот стандарт рекомендует только для PSR. А не для кода. Т.е. эта рекомендация не входит в PSR-1 или PSR-12. Видимо, там таки нашлись здравомыслящие люди, которые сумели отговорить PHPFIG эту спорную идею выносить как стандарт для всех.

Storage - неплохое. Ну может FileStorage чуть поточнее будет. Это хороший пример класса, которые в начале развития проекта, скорее всего будет одним на весь проект, а потом необходимо будет интерфейс FileStorage и несколько его реализаций: LocalFileStorage, S3FileStorage и т.д.

FileStorage - отличное имя. Смотришь на него и всё отлично. Необходимая информация передана за маленькое количество букв. Ежу понятно, что это хранилище файлов. Причем, что именно за хранилище - непонятно и это тоже хорошо. Это абстракция :) Ну вот представь, у тебя в проекте сотни раз использовано наименование класса или интерфейса, которое отвечает за хранение файлов. Что ты предпочтешь? FileStorage? Или FileStorageInterface, FileStorageContract? FileStorageClass? Разумеется первое. Лет 6-7 назад я тоже думал, что очень важно знать интерфейс это или класс мы сейчас хотим использовать? Но посколько везде используется DI и мы не должны делать сами какое нибудь new FileStorage(), то нам вообще всё равно что стоит за этим именем.

НУ и напоследок банально рассмотрим ситуацию где интерфейс и реализация.
Что лучше: interface FileStorageInterface. class FileStorage implements FileStorageInterface и еще сотни FileStorageInterface в проекте
Или interface FileStorage. class LocalFileStorage implements FileStorage и еще сотни FileStorage в проекте?

Простое название FileStorage мотивирует давать говорящие имена классам, а не просто тупое Имя интерфейса без суффикса. Это тоже полезно.

[gzhegow1991]

На мой взгляд, всё несколько проще.
Интерфейс сегрегация есть такое слово.

Поясню на пальцах.
Вы нанимаетесь на работу и подписываете контракт.
Контракт это интерфейс на вас (должностная инструкция) - вы умеете делать то-то, вот то и то (методы) + знаете то-то и то-то (константы). В контракте меняется только ваша фамилия (реализация).

Сегрегация интерфейсов это про то, что вместо контракта на "программиста" пишется контракт на "умение писать код" отдельно, отдельно на умение "знать то-то", отдельно на умение делать что-то еще.

Это позволяет вам потом создать общий контракт соединив мелкие в один (множественное наследование интерефейсов в PHP отлично работает, а классов можно сделать трейтами, но это надо делать только там, где иначе - невозможно).

Вот StorageInterface подразумевает, что вы сразу создали гигантский контракт. Это не плохо, когда вы создаете что-то с нуля чаще всего так и делается - вы просто валите всё в интерфейс, а можно даже не делать интерфейс и просто валить в сам класс.

Чуть позже вы понимаете что некий кусок функционала будет подменяться - например перводчик будет уметь это делать гуглом и яндексом, а статистика будет забираться с аналитики, вебмастера и гемиуса. Вот тут вам нужен какой-то ключ, с помощью которого вы будете менять одно на второе в общем случае. Вот тут появляется интерфейс AnalyticsInterface, который уже не гугловский, а ваш, конкретный, так сказать "доменный", "принятый в вашем проекте/команде"

Но бывает что вам не нужно заменять сразу весь функционал аналитики, а нужно нарастить часть её функционала в другом классе (трейт написать). Вот тут вам на помощь пришел бы мелкий интерфейс, который будет являться частью наращиваемого класса И вашего класса анатилики (функицонал в двух местах).

Это не значит что это правильно. Это удобно в моменте.
Чуть позже у вас может появится отдельный класс, который будет делать это над переданным обьектом (над любым), а не два функционала в двух местах с одним интерефейсом, которые делают что-то над самим собой.

Возвращаясь к предмету дискуссии - StorageInterface подразумевает, что сюда можно всунуть абсолютно любое хранилище чего-либо. Это не плохо опять же, но это слишком гигантский и всеобъемлющий контракт! Чтобы написать настолько стандартизированную инструкцию, чтобы сохранять что угодно куда угодно при помощи двух кнопок можно крышей уехать. Поэтому верно - разумнее сделать FileStorage класс, который хоть немножко уменьшает обобщение, и говорит о том, что это хотя бы хранилище файлов, а еще лучше FilesystemStorage, которая уже говорит что это хранилище на вашем жестком диске. И суффикс "Interface" к нему добавится тогда когда у вас появится AudioFilesystemStorage, VideoFilesystemStorage, ImageFilesystemStorage, AudioAwsStorage, VideoAwsStorage, ImageAwsStorage. В этом случае FilesystemStorageInterface (не важно что) ограничит хранение на локальном диске, а AudioStorageInterface ограничит хранение только для аудио (не важно куда)

Сделаю маленькую ремарочку на тему "супер интерфейса" - есть такая вещь как Psr\Cache. Так вот все мировое сообщество ПХПшников 20 лет пытается стандартизировать кеширование, и придумало раза с 20го только CacheItemPoolInterface, и то в нем нет гарантии, что поддерживаются теги. То есть суперпулю пытались делать, но поняли, что лучше ее наворачивать по ходу, выбрасывая постоянно повторяющиеся штуки в стандарты, а не садиться и ордой вокруг круглого стола стандарт писать.

Смысл в том, что разработка меняется по мере допилок, когда ты понимаешь что "это надо", а не сразу вы заложили и на века. Так не бывает.

Чтобы наращивать функционал - чем интерфейсы меньше - тем лучше. Чтобы подменять функционал - чем интерфейсы больше, тем легче его подменить целиком, т.к. не надо разбираться из каких частей он состоял.

Собственно если взять Симфони - они активно используют "алиасы", которые в других фреймворках обозвали (и обложили) сервис локаторами (а сами тут же сервис локаторами назвали "умные факторки" и вообще все напутали). Чтобы не спамить большими интерфейсами предлагается просто давать некоему обьекту текстовое имя типа "app.serializer" после чего в конфиге ВРУЧНУЮ его пропихивать в обьект (т.е. автоподстановка не будет работать, а будет ручная, которая быстрее, но которую дольше менять в коде и помнить о ней).

Поэтому сначала чему-то присваивается алиас, а потом на входе конструктора можно указать или имя класса в которое превратится этот алиас, или интерфейс, если хочется прям совсем полную подменяемость.

[DplusG]

Конкретно от слова Interface можно и отказаться, как от венгерской нотации.
Хотя ничего криминального не вижу, и дело привычки. Как и Interface|Contract
Причем в куче мест вы скорее всего встретите приписку Interface как в том же PSR.

"просто для юнит-тестирования" - как-то обесценивает :)

А от других приписок уже не получится отказаться. Например, Contact::class.
Что перед нами? Controller, Enum, Factory, Request, Model, Repository, Service?
Вот и получается потом что-то вроде такого:
ContactController,
ContactRoleEnum,
ContactFactory,
AddContactRequest,
ContactModel,
ContactRepository,
ContactService

Да, они указывают на слой. Но определенное представление о типе также появляется. По наименьшему удивлению вы не ожидаете увидеть в ContactRoleEnum экшен, а скорее всего какой-то набор key,value список

[gzhegow1991]

Точно!

Однако я предпочитаю не лениться и писать Interface в конце и Abstract в начале, ибо интерфейс хорошо заметен в use блоке, а Abstract отлично сортируется по алфавиту, и все абстракции сразу оказываются выше деталей.

Я не смог найти вас в телеграм, давайте поддерживать связь, спасибо!

[adelf]

А от других приписок уже не получится отказаться. Например, Contact::class.
Что перед нами? Controller, Enum, Factory, Request, Model, Repository, Service?

Иногда делают исключение для какого-то одного типа и обычно классы сущностей называют без суффикса. Просто Contact.

все абстракции сразу оказываются выше деталей

И все-таки. Зачем знать в конкретном месте, если мы используем таки DI, интерфейс это или класс(абстрактный или нет)?

[gzhegow1991]

Честно говоря может просто привычка.
Мне субьективно удобнее в шторме в дереве видеть что вот абстракции и вот они выше, чем не абстракции.
С интерфейсами то же самое - когда пишу use чтобы ничего не напутать, если интерфейсы из вендоров использую, всегда алиас создаю. Зачем? Чтобы потом не жалеть...

Вообще на днях пытался задвинуть errorBag в php-internals. Обгадили. Сказали "так нельзя делать, ужас!", но блин, я не видел еще в своей жизни тимлида который готов сесть и с тобой диаграмму методов по солиду раскладывать. Ставят задачу в которой метод сначала здоровенный и гигантский, и сильно удобнее ошибки собирать глобально по скрипту, и потом в апи их выплюнуть, чем дробить на микрометоды и эксепшены лютую интеграцию методов на 400 (которая по солиду станет тысячи три методов)

https://github.com/6562680/error-bag

[DplusG]

обычно классы сущностей называют без суффикса

Согласен, увлекся) но можем еще и ContactList|ContactCollection получить. Это больше как иллюстрация, что не все суффиксы получится убрать

[adelf]

@DplusG Я не против суффиксов. Они хороши. Практически все приведенные тобой. Я против конкретно *Interface, *Contract, и прочей ерунды)

[gzhegow1991]

ну я чессговоря хорошенько навозился с ларавелем, где без суффиксов многие интерфейсы называются и потом еще симфони добавился, и сторонние либы... я, значит, оборачивать и в контейнер класть, и пошла путаница в use, выпадает в подсказке оба, и пока не чекнешь не знаешь что это

[adelf]

@6562680 если стараться нормально называть, то проблем быть не должно. Например LaravelConfig implements Config. CloudFileStorage implements FileStorage.

[DplusG]

https://github.com/6562680/error-bag

Попробовал въехать в твое предложение и, честно говоря, все равно не понял почему try-catch не вариант. Ну или ***Response, который нужное в себе содержит

метод сначала здоровенный и гигантский

Тут уже наводит на мысли, что на методе слишком много ответственности и error-bag будет лечением последствий, а не причин

[gzhegow1991]

ну как не вариант, это не альтернатива, это дополнение к try/catch

try/catch разруливает простые функции, и вешает прогу.
сборка ошибок не вешает прогу, не должна вешать.
и потом когда ты new Exception() вызываешь собирается трейс.
если в исходном массиве для batch у тебя есть ошибочные варианты, которые ты сначала бросаешь, а потом ловишь - ты дважды теряешь время на сбор трейсов и отлов.

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

то самое понятие "что-то пошло не так" - которое должно сказать тебе, что код надо менять.

если все прошло правильно, но выпало исключение - то оно должно стать warning, а значит не было смысла собирать трейс для него, все равно на вывод пойдет скорее всего ->getMessage(), а трейс собирается не когда ты попросил, а когда ты вызвал new \Exception().

простейший пример где исключения дают "приехали" - это массовая работа с чем-либо.
берешь с очереди или в кроне 10 записей. при этом 5 из них повторяются. то есть отправить в интеграцию/api можно (и нужно) только 5. т.е. в худшем случае "исключений" будет 5. а в исходной бд с очередью куда надо логи положить - ячеек 10. надо откопировать, форматировать, в массивы положить. всё это пишется на форичах обычно. и в добавок возвращается из функции.

но на практике твой код был уже готов, например, и завернут уровней в 8 (лесаси или сложная интеграция). ну и чтобы ошибки собрать иди меняй сигнатуру всех восьми уровней вложенности и проверяй все места где вызывалось вручную, чтобы поймать вывод и передать его дальше.

а если не поймаешь - то схлопнется логика, которая должна была продолжиться.

вот почему ошибки это не исключения.

[gzhegow1991]

метод сначала здоровенный и гигантский

да. солид отталкивается от идеального мира, где методы маленькие и прозаичные.

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

то есть оттолкнуться от того, что "код не идеальный" это уловка учёных, которые не являются инженерами. в итоге приходится втыкать ускорители-кеши там где их быть не должно, чтобы скрыть неэффективную работу.

так вместо этого мировое сообщество решило упороть людей в O log N анализ скорости выполнения функций (смотри все эти идиотские mock-собесы), который в общем-то очень нужен, но опять же - для идеального мира, и если по правилу парето - то для тех самых 20 случаев из 100, на которых нужно много работы и которые сработают почти никогда, но могут.

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

[DplusG]

@6562680, а ошибки на уровне записи в БД или соответствие типам или еще что-то?

Мне пока видится, что должно это решаться в userland:

1. Обход списка, валидация каждого элемента. При ошибках не бросать исключения, чтобы трейсы не собирать.
2. После этого что-то вроде $list->getErrors()
3. Дальше уже либо выбрасывать исключение/response в таких-то элементах у вас проблемы. В зависимости от того, записывать надо пачкой или только валидные.
   Если пачкой - можно и exception.
   Если валидные - {message: "записано 3 из 10"}

[gzhegow1991]

@DplusG

не, с чего бы на уровне бд. возьмем интеграцию с почтовым сервисом например. ты формируешь очередь команд, которая либо сразу разбирается если это раббит, либо "упрощенный" способ - крон. (даже здесь есть уловка, что это дескать одно лучше другого, но на самом деле правильная очередь работает по обоим критериям - набрать десяток, или если за минуту не набралось, то сделать сколько набралось)

из базы все вытащил. оно легло туда валидное и ты все проверил. шлешь его на внешний сервис. внешний сервис вернул ошибки, хотя с твоей стороны все валидно. запросы надо повторить или пометить статус операции в fail, начать откат. т.е. в вышеописанном случае возьмем худший сценарий - было 10 телефонов, послал 5 (ибо повторы) и все 5 вернули ошибку. нужно 10 операций пометить что они FAIL, а не 5, хотя внешняя интеграция ошиблась 5 раз.

безусловно приятно, что ошибки ломают прогу и триггерят тебе на почту, что код на той стороне теперь косячит (что-то могли поменять) и тебе надо довести свой до ума. но это поломает тебе сайт... теперь твои юзеры столкнулись с проблемой, когда они видят 500 ошибку там, где ты вообще ничего не трогал. с точки зрения клиента лучше бы они видели "операция не удалась" и пинговали поддержку, чем прога мертво начала падать в 500, потому что теперь там исключение.

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

ты совершенно правильно говоришь насчет валидации. единственное терпимое решение, которое УМЕНЬШАЕТ (а не РЕШАЕТ) количество проблем до минимума - это валидация данных как можно раньше. Но внешний сервис все равно может вернуть рантайм ошибки, которые можно итерационно допилить в валидации конечно, но хотелось бы, чтобы они сразу были ошибками без триггера 500-ки.

т.е. тру подход это сначала раздробить код на микрометоды по 1-2-3 строки, затем валидацию поближе к месту начала задачи, но это все сильно увеличивает и количество кода и вероятность 500 там где не должно. это хорошо и правильно с точки зрения надежности, но требует каждый раз переделки концептуально. а мы то целимся в то, чтобы старый код не трогать (стараться не трогать), если что-то создает причины для изменения, то оно верно с научной точки зрения (той самой которая повышает тебе ЧСВ), но неверно с бизнесовой (с той самой, которая заставляет тебя срочно выйти на работу в выходной)