Документация многими считается обязательной для успешных проектов, но действительно ли она так эффективна? Я зачастую вижу чрезмерные ожидания, но есть ряд проблем:



1️⃣ Устаревает быстрее, чем кажется: Код меняется, а документация — нет. Поддерживать её в актуальном состоянии сложно, а устаревшие документы только путают.

2️⃣ Иллюзия контроля: Красиво оформленный документ создаёт ложное чувство понимания и контроля. Кажется: «раз написано, значит, всё ясно». На деле же это может быть не так.

3️⃣ Синдром «написал и забыл»: Многие пишут документацию потому, что «так надо», а не потому, что она действительно полезна. Её почти никто не читает, и уж тем более не обновляет.

4️⃣ Валидация у доменных экспертов? Почти никогда. Техническая документация редко проверяется экспертами предметной области, что приводит к пробелам в знаниях и ошибочным допущениям.

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

Друзья, с Новым годом! ☃️
Желаю всем интересных проектов, крутых коллег и непрерывного развития. К последнему я постараюсь приложить свою руку. И начнем с короткого списка относительно свежих/ожидаемых книг.

The Hundred-Page Language Models Book — Андрий Бурков https://thelmbook.com

Андрей, автор известной The Hundred-Page Machine Learning Book, готовит к выходу The Hundred-Page Language Models Book. Эта лаконичная книга фокусируется на фундаментальных основах LLM и станет незаменимым пособием для инженеров, дата-сайентистов и AI-энтузиастов, желающих разрабатывать или использовать LLM.

The Developer Experience book — Николь Форсгрен и Аби Нода https://developerexperiencebook.com

Николь Форсгрен и Аби Нода, соавторы и эксперты в области производительности разработчиков (Accelerate), исследуют тонкости DevEx. Жду, когда эта книга будет опубликована.

Become a Great Engineering Leader — доктор Джеймс Стэниер https://www.theengineeringmanager.com/book/

Доктор Джеймс Стэниер, автор Become an Effective Software Engineering Manager, представляет новую книгу Become a Great Engineering Leader. Это практическое руководство для старших руководителей, таких как директора по инженерии, вице-президенты и технические директора. Оно охватывает такие темы, как управление менеджерами, разработка стратегий и построение карьерного пути, предоставляя дельные советы по созданию высокоэффективных организаций.

Facilitating Software Architecture — Эндрю Хармел-Лоу https://facilitatingsoftwarearchitecture.com

Эндрю Хармел-Лоу, эксперт в области гибкой архитектуры, предлагает новый взгляд в своей книге Facilitating Software Architecture. Эта книга переосмысливает роль архитектора в современных программных системах, акцентируя внимание на сотрудничестве вместо централизации. Хармел-Лоу делится практическими методиками, позволяющими объединить архитектуру и гибкие практики, чтобы создать устойчивые и эффективные системы.

Flow Engineering: From Value Stream Mapping to Effective Action — Стив Перейра и Эндрю Дэвис https://flowengineering.org

Стив Перейра и Эндрю Дэвис, эксперты в области value stream mapping, представляют книгу это руководство по оптимизации рабочих процессов и согласованию команд. Объединив принципы value stream mapping и системы Toyota, они предлагают практические инструменты для ускорения инноваций и улучшения взаимодействия команд.

Что читаете вы? Поделитесь, дополню свой вишлист🙏

Завтра планируется интересный стрим. Рекомендую послушать, особенно если не очень знакомы с концепцией CDC в целом и с Debezium в частности https://www.youtube.com/live/IPV6WVx71k8

Влад @vladik_kh пообщался с ребятами из {между скобок}

Получилось как всегда интересно и полезно – https://www.youtube.com/watch?v=PRL3vVfv1dA

Влад нарасхват ☺️ https://www.youtube.com/live/7j6eoTMM-Xc

Сейчас пилотирую на одном пет-проекте ИИ помогатора.
Стек: реакт на фронте, dotnet8 (minimalapi aot) для апи. Для понимания – последний раз регулярно писал для прода на фронте во времена jquery/angular 1.x, c# - наоборот основной язык и что-то я в нем понимаю.

В качестве помогатора был взят Windsurf https://codeium.com/windsurf

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

Что могу сказать:
1. Это очень круто. Я не представляю сколько бы времени у меня ушло собрать все эти vite, husky, jest и прочий фронтендовый тулинг. И еще больше на разобраться с реактом, версткой и тп. Здесь же спустя пару часов тыкания, корнер кейсов и прочих объяснений у меня уже был проект с парой страниц, с тестами, с автодеплоем по пушу и прочим. Общался я с помогатором и CLI тулами, код руками не трогал.
2. Бекенд я начал писать сам, еще до windusrf. Да и потом некоторое время боялся отдавать, но хотелось ускориться и помогатор неплохо справился. Единственное но – в райдер сложно встраивать плагины и приходится писать в двух окнах: руками в райдере, помогатором в VSCode (точнее в их версии VSCode).
3. При больших изменениях жди больших бед, приходилось тормозить.
4. Помогатор владеет тулингом: доступ в бд, логи, гитхаб, облако. И классно этим пользуется, чтобы проверить результат свой работы, если видит свой продолб – сам исправляет, коммитит пушит.
5. Помогатор на фронте не видит своей работы. И этого очень не хватает. Говоришь:

– сделай по центру.
– Ага, вот да, вот поправим то, поправим это... Готово!
– Нет, ничего не поменялось, контент по-прежнему прибит к левому краю.
– Со сорри, я понимаю ваше разочарование. Да я вижу причину, сейчас мы все поправим...бамс-бамс-бамс... Готово!
– 🤬 все по старому!
...

Мне кажется это потенциальная точка роста для таких систем (ну пока пишут софт для кожаных мешков с колбочками).


Что важно?
А важно то, чему нас учили все эти ребята из книжек про разработку, только теперь это еще важнее:
1. Быстрая обратная связь: у вас должны быть юнит-тесты с принудительным запуском на пре-пуш хуке, у вас должен быть CI-CD, у вас должны быть e2e автотесты, у вас должен быть мониторинг и хелс-чеки. Вы начали писать код в разы быстрее и не можете себе позволить тратить дни на полный регресс.
2. Беби степы (как учил Кент Бек). Пару раз помогатор мне разваливал проект. Из-за отсутствия быстрой обратной связи я слишком поздно понимал, что ушел не туда, а так как это эпизодический пет-проект, то спустя неделю я уже не мог вспомнить как я пришел в эту точку. В итоге маленькое изменение, прогон тестов, выкладка и прочее, повторить.
3. Следите за тестами. Их надо писать, возможно даже больше чем хватило бы при обычной разработке. Можно попробовать писать по ТДД. И следите, чтоб помогатор при падении тестов фиксил код, а не переписывал тесты)
4. Размер контекста важен. LLM плохо умеет в огромные конексты. И вроде эту особенность пока не получается победить (к сожалению или к счастью). Так что вам надо здесь помочь помогатору и самостоятельно нарезать куски. Все это также верно и для человеческой разработки.
5. Без разработчика пока что никуда. Я читал посты продАктов как они собрали проект на флаттере с бекендом без технического бэкграунда. Но я не понимаю как. Может проекты совсем уж простые, но у меня пару раз уходил совсем не туда. И только мой опыт помогал мне вырулить ситуацию.
6. Мне кажется (хоть я пока и не пробовал) парное программирование (человек-человек-помогатор) это просто бомба. Быстро, качественно и весело!

Поделитесь вашим опытом/видением/мнением

Очередной радар уже здесь, давайте посмотрим, что интересного на этот раз.

1. Надо ли говорить, что заметная часть элементов радара так или иначе связана с AI и языковыми моделями (большими и малыми)? Агенты и Model Context Protocol сюда же.
2. Внезапно большой кусок про Open Telemetry. Здесь и тулинг от Графаны (Alloy, Loki, Tempo) так и сама https://opentelemetry.io. Странно, потому, что я думал, что хайп прошел и все уже и так пользуются всем что надо.
3. Опять на радар попал https://dapr.io - давно болтается в заметках. Есть кто использует? Поделитесь опытом!
4. uv (от себя добавлю ruff) – тулинг для Python от Astral на расте
5. Supabase - хостинг приложений. Google Firebase знаешь? Только черный!
6. Еще одна девопс тула https://www.systeminit.com, из описания в радаре ничего непонятно, надо потрогать поближе.
7. Мой любимый https://codeium.com/windsurf тоже здесь ❤️


Что приглянулось вам?

Сразу два анонса о переходе с открытых лицензий на коммерческие
https://www.jimmybogard.com/automapper-and-mediatr-going-commercial/
https://masstransit.io/introduction/v9-announcement

Я стараюсь регулярно изучать новое и периодически пишу про разные курсы/платформы

Сегодня обзор Cloud Skills Boost oт Google. Это платформа для изучения Google Cloud Platform: различные стораджи, k8s, AI-ML и все остальное.

Есть курсы по темам, курсы объединены в Learning Paths по различным направлениям (Developer, SRE, Data Engineer, Architect, etc).

Курс – набор роликов, заданий, тестов и лабораторок. Все лабораторки проходят на предподготовленных учетках в GCP. Очень удобно и полезно, что это не просто какой-то урезанный тренажер, а полноценная учетка, которую можно использовать как через интерфейс, так и через их CLI gcloud.

Качество роликов среднее, по мне их слишком уж мелко нарезали. Тесты и задания адекватные.

Есть бесплатный доступ, но есть и подписка ($300 в год).
В подписку входит доступ к платформе со всеми лабораторками, ваучер на сертификат, $1000 на поиграться в GCP. Ваучер был успешно конвертирован в сертификат😎

Тест на сертификат проходит онлайн (есть опция и оффлайн). Используется специальный софт, который лочит лишние приложения и следит за поведением. Обмануть наверное можно, но там много что контролируется. 50 вопросов, надо выбрать единственный правильный ответ, писать ничего не надо. Сложность средняя, частично можно отвечать просто на общем опыте или путем исключения заведомо неподходящих вариантов, но, кажется, просто сходу не сдашь, нужен именно опыт использования – заучить это все крайне сложно. При успешном прохождении не раскрывают ничего про правильность ответов, так что я не знаю где я насколько я оказался хорош.

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

И да, минутка хвастовства: теперь я Клауд Архитектор https://www.credly.com/badges/b5d2acdc-9170-41e4-8f35-bbdf49190e68/public_url

#обучение

Попалась статья про концепцию The Synchrony Budget. Основной посыл: взаимодействие между сервисами
должно быть настолько асинхронным, насколько это возможно, и настолько синхронным, насколько это необходимо.
И вроде бы да: мир в котором мы живем в большинстве случаев асинхронный: мы асинхронно заказываем такси, асинхронно получаем аппрув на наше заявление об отпуске, асинхронно торгуем на бирже, асинхронно переводим деньги. И в целом strong consistency переоценена и редко где нужна.
Но как всегда everything is a tradeoff! Как монолит намного проще микросервисной архитектуры (рекомендую ознакомиться с fallacies distributed system), так и синхронное взаимодействие намного проще асинхронного.

Вот моя версия fallacies asynchronous communication:

Заблуждения об асинхронной коммуникации
Часто встречающиеся ошибки, из-за которых распределённые системы становятся хрупкими и непредсказуемыми

1. Инфраструктура надёжна, поэтому о согласованности можно не думать
Полагаться на то, что платформа “всё сделает правильно”, опасно
→ Реальность: Сеть может моргнуть, сервисы — упасть, сообщения — потеряться. Согласованность должна быть заложена в архитектуру.

2. Сообщения будут обрабатываться в том порядке, в котором были отправлены
Опираться на порядок событий — прямой путь к скрытым багам и несогласованному состоянию
→ Реальность: Порядок доставки не гарантируется — используйте ключи сортировки или обрабатывайте события с учётом возможной перестановки.

3. Каждое сообщение будет обработано ровно один раз (exactly once)
Ожидание, что каждое сообщение придёт ровно один раз, может привести к логическим ошибкам из-за повторной обработки.
→ Реальность: Почти все системы доставляют сообщения по меньшей мере один раз (at least once) — логика обработки должна быть идемпотентной.

4. В асинхронных системах нет гонок (race condition)
Асинхронность не избавляет от проблем с параллелизмом
→ Реальность: Задержки, повторы и параллельная обработка могут приводить к состоянию гонки. Требуется защита общего состояния и продуманная архитектура.

5. Консьюмер обработает сообщение быстро и предсказуемо
Расчёт на стабильное время обработки приводит к неправильным архитектурным решениям
→ Реальность: Обработка может занять секунды или минуты — в зависимости от нагрузки, состояния системы или внешних зависимостей. Нужно заранее определить: как долго ждать, когда реагировать, что делать при задержке.

6. Поддерживать контракты сообщений и отслеживать кто что продюсит и консьюмит просто
Игнорирование связей между компонентами приводит к неожиданным сбоям
→ Реальность: В асинхронных системах компоненты слабо связаны — используйте реестры схем, определяйте владельцев и версионируйте контракты.

7. Асинхронность снижает связанность (coupling), значит менять контракты легко
Считать, что слабая связанность позволяет менять сообщения без последствий — опасное заблуждение
→ Реальность: Форматы сообщений — это публичные API. Изменения должны быть обратимо совместимыми, задокументированными и согласованными.

8. Достаточно просто отправить сообщение — оно обработается
Игнорирование доставки приводит к потерянным данным и бесшумным ошибкам
→ Реальность: Без гарантии доставки и мониторинга невозможно быть уверенным, что сообщение дошло — используйте dead-letter очереди, логгирование и метрики доставки.

9. Повторить попытку — значит решить проблему
Безграничные повторы создают нагрузку, дубли и повторяющиеся ошибки
→ Реальность: Нужны ограничения на повторы, экспоненциальные задержки, таймауты и dead-letter очереди — повтор сам по себе проблему не решает.


Асинхронное взаимодействие добавляет сложности и я НЕ рекомендую делать выбор по умолчанию в пользу асинхронщины. А если и выбирать, то не забывайте об этих заблуждениях!

Обсудим? Что добавили бы? Какой выбор по умолчанию у вас?

Очень полезная и практичная статья про то как развивать принятие архитектурных решений в компании https://martinfowler.com/articles/scaling-architecture-conversationally.html

Если коротко, то есть правило: любой человек может принять архитектурное решение.

Но перед принятием решения лицо, принимающее решение, должно проконсультироваться с двумя группами: Первая - это все, на кого решение окажет существенное влияние. Вторая - люди, обладающие опытом в той области, в которой принимается решение.

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

1. АДР - про них уже много писали и обсуждали в чате, можно почитать здесь https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records

2. The Architecture Advisory Forum - архитектурный советю По сути централизованное место для изначального ПРАВИЛА.

3. Общие архитектурные принципы. И это должны быть не просто лозунги типа KISS, DRY и прочего.

4. Свой техрадар https://www.thoughtworks.com/radar/byor


Подробнее как зачем и что читайте в статье

Есть отличная книга https://jacquiread.com/books/communication-patterns/

Джеки Рид пишет (и рассказывает на конфах) как правильно и нашем мире разработки и не только доносить свою мысль до целевой аудитории.

Сложно выделить какие-то отдельные поинты, это скорее сборник паттернов, рецептов и советов.

Книгу рекомендую как минимум полистать, а еще попалась шикарная преза, где эти паттерны собраны и красиво визуализированы

Не чекал полностью, ео вот и видео к презе https://www.youtube.com/watch?v=JUqrNWKPMYA

Можно использовать для быстрого погружения новичков или при подготовке к собесу, если вы не очень знаете DDD 🙈

Вчера вышла очень интересная заметка на тему нашей любимой методологии "что, как и зачем". Можно использовать в качестве шпаргалки для себя или показать новичкам для быстрого ввода в курс дела.

В Португалии и части Испании глобальное отключение электричества. Света не было примерно 9 часов. Не было инета, мобильная связь работала местами и с перебоями. Кассы в Ашане пока работали, но не долго.

А как ваши системы пережили бы такое?

Дядюшка Боб ака Роберт Мартин неплохо вчера накинул на sql. Основной тезис в том, что зря мы взяли текстовый контракт для взаимодействия и нам нужно полноценное апи

Недавно дискутировал с коллегой про виды двойников (aka test doubles). Я отстаивал право на существования фейков, он топил за то что есть моки, а остальное и не надо вовсе. Этому спору лет 20 на самом деле, и там сломано столько копий, что уж и не сосчитать. И конечно, я не собираюсь сейчас объяснять какой подход лучше. Всем и так очевидно, что тот где тестируется состояние с использованием фейков, Object Mother и прочего.

Но мне стало интересно, что говорят наши Лучшие Лидеры Мнений (то есть LLM).

Подготовил максимально нейтральный промпт:

Provide an example unit test for methods that involve interfaces in .NET 8, using any public libraries.

и прогнал его через несколько моделей (sonnet, gemini, grok, gpt, deepseek...):

Все модели в своих примерах использовали xunit и moq (самая популярная библиотека в дотнет мире для мокирования). Думаю, что подход с моками сейчас в лидерах и дальше он будет набирать все большую долю, так как новички и кодогенерация будут использовать моки все чаще и чаще. Ведь если либа-утилита используется в ответе без явного упоминания – это хороший знак! Ее начинают использовать, новый код опять подтверждает приверженность этой либе и еще чаще попадает в ответы.

Кажется, что технопиар должен быть сейчас направлен на то, чтоб либа попала в кодогенерацию, этакое новое SEO. Может даже появятся профессия вроде Prompt Evangelist или LLMRel – человек, который убеждает модели выбирать правильную либу.

Как-то я привык, что про DDD говорят и пишут преимущественно разработчики. Поэтому особенно рад поделиться этой статьей от продакта/аналитика Иннокентия Бодрова. Возможно, опытные завсегдатаи и не найдут много нового в статье, но можно взять в закладки, чтобы кидать своим продактам или аналитикам.

https://habr.com/ru/articles/908782/

Плюсики на хабр, вопросы и комментарии – сюда, @InnokentyB с нами

Можно по-разному относиться к вайб-кодингу и кодинг ассистентам, но так или иначе подход к разработке уже поменялся и будет меняться дальше. И надо знать не только сильные стороны, но и уязвимые места. В блоге у Фаулера вышла новая статья с обзором некоторых возможностей потенциальных проблем. https://martinfowler.com/articles/exploring-gen-ai/software-supply-chain-attack-surface.html