4 posts
Literate programming поддерживает синхронизацию документации, тестов и реализации, делая Markdown-файл единственным источником правды. Вот как реализовать это тридцатью строками на Python.
Ваша документация, тесты и код — это три файла, которые плохо рассказывают одну и ту же историю. Вы обновляете сигнатуру функции в исходнике. Забываете про…
Диалоги с LLM содержат намерения, отвергнутые альтернативы и работающий код. Именно это и должна представлять собой документация. Вот как превратить эфемерный чат в долговечные, доступные для поиска документы, не теряя повествования.
Вы провели сорок пять минут с Claude, проектируя схему повторных попыток. Вы объяснили режимы отказов, отвергли экспоненциальный откат, потому что он скрывает…
Literate programming обещала, что код должен писаться в первую очередь для людей, а во вторую — для машин. Четыре десятилетия спустя почти никто так не пишет. Вот почему самая элегантная идея в документировании программного обеспечения не смогла изменить наш способ работы.
В 1984 году Donald Knuth опубликовал статью, в которой предложил радикальное изменение. Программы не должны писаться для компиляторов и комментироваться для…
Архитектурная документация гниёт в тот момент, когда вы её сохраняете. Вот как поддерживать её в актуальном состоянии с помощью диаграмм, генерируемых из кода, ADR и автоматизированных архитектурных тестов.
Каждая архитектурная диаграмма, которую я видел в вики, была неверной. Не катастрофически неверной. Просто тихо, постепенно неверной. Сервис с пометкой «Auth»…