Tl;dr: дока только через автоген, а чтобы этого достичь иногда можно и нужно срать на стандарты
Как-то меня последний год обходила стороной необходимость вручную писать доку. Сначала был graphql, где доку вообще делать не надо, а потом перешёл на проект на симфони, где дока генерится при деплое исходя из аннотаций на экшене контроллера.
Я даже и не подозревал, во-первых, насколько это удобно, а во-вторых, насколько это важно для скорости разработки и главное для желания вообще хоть что-нибудь разрабывать и менять.
Извечная проблема программистов в том, что программу постоянно надо менять и чем легче это делать, тем нам проще.
Так вот я все это к чему: на подработке используется yii2 и еще мои собственные наработки, максимально облегчающие разработку апи, НО! совершенно не трогающие момент с документацией. Из-за этого приходилось руками писать доку на аннотациях в пхп, следя, не забыл ли я случайно где-то параметр или тот ли я указал тип. Это жопа. Это трудоемко, это пустая трата времени.
Плюнул, потратил 3 часа на полную переработку подхода и в итоге получил автогенерацию доки при деплое, прямо как на основной работе. Вдовесок к этому получил полную типизацию всех возвращаемых значений при обработке данных. Двойной выигрыш.
Есть очевидный минус — в классе, производящем обработку данных, мы теперь имеем аннотации, относящиеся к документации апихи, о которых класс знать не должен вообще. Плохо ли это? Очень! Но мне абсолютно все равно🤣 В конце концов, код выполняет свою цель, не сильно при этом засираясь. Более того, такой подход куда практичнее, чем многоуровневый маппинг с "запросов" на "команды", а потом на "ответы".
Но давайте я все же подчеркну основную мысль — это не энтерпрайз и это не команда из 10 человек, я тут один. Тут срать все хотели на подобные мелочи, заказчику важен результат здесь и сейчас. Соответственно, и подходы мной выбираются исходя из этого.
Писать чистый совершенный код невозможно, абсолютно в любой ситуации придется чем-то жертвовать и уж лучше это будет небольшое нарушение разделения зон ответственности, чем мое время и нервы
Добавить комментарий