literate-programming

6 статей

Назад ко всем статьям

Ваша литературная программа сломана, пока CI не может сделать tangle без вас

Literate programming обещает единственный источник правды, но ручные шаги weave и tangle ломают CI/CD-пайплайн. Вот как автоматизировать извлечение и генерацию документации, чтобы ваши Markdown-файлы оставались каноническими.

Я перестал копировать код в документацию, храня тесты, код и прозу в одном Markdown-файле

Literate programming поддерживает синхронизацию документации, тестов и реализации, делая Markdown-файл единственным источником правды. Вот как реализовать это тридцатью строками на Python.

Ваш тред в Claude уже является документацией. Он просто умрёт через двенадцать часов.

Диалоги с LLM содержат намерения, отвергнутые альтернативы и работающий код. Именно это и должна представлять собой документация. Вот как превратить эфемерный чат в долговечные, доступные для поиска документы, не теряя повествования.

Текстовые редакторы позволяют писать невалидный код. Древовидные редакторы не позволили бы.

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

Donald Knuth хотел, чтобы программы читались как литература. У компилятора были другие планы.

Literate programming обещала, что код должен писаться в первую очередь для людей, а во вторую — для машин. Четыре десятилетия спустя почти никто так не пишет. Вот почему самая элегантная идея в документировании программного обеспечения не смогла изменить наш способ работы.