literate programming

В целом тыренный «монстр Франкенштейна», пока не собрано в норм текст.

Literate Programming — концепция, методология, парадигма программирования и документирования, согласно которой код нужно писать таким образом, чтобы он был понятен людям, читающим его. Термин и саму концепцию «грамотное программирование» разработал Дональд Кнут в 1981 году при разработке системы компьютерной вёрстки TeX.

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

Эта методология не зависит от языка, прочих используемых методологий и особенностей устройства программы. Она касается способа работы с написанием кода и документации, требующего подходящих инструментов в процессе. Код здесь пишется параллельно с документацией, и зачастую позже документации. Исходники структурированы в соответствии с логикой изложения мысли, чтоб было удобно читать и думать. Для того, чтоб собственно использовать код, надо сначала его tangle - отделить от документации и расположить в соответствии с требованиями языка программирования.

Позволяет сочетать методы «сверху вниз» и «снизу вверх». И вообще позволяет. Держать в голове, помнить, понимать…

Отличается от так называемого "inverted literate programming", каковое есть извлечение документации из обширных комментариев, использующих какой-либо язык разметки. Ибо в этом случае последовательность и логика изложения продиктована используемым языком, намерения автора остаются где-то в стороне. Кажется, часть народу на том же хабре literate programming видит именно как безумно избыточное комментирование в таком духе. Что неверно.

Literate programming is an excellent method for documenting the internals of software products especially applications with complex features. Literate programming is useful for programs of all sizes. Literate programming encourages meaningful documentation and the inclusion of details that are usually omitted in source code such as the description of algorithms, design decisions, and implementation strategy. Literate programming increases product quality by requiring software developers to examine and explain their code. The architecture and design is explained at a conceptual level.

Modeling diagrams are included (UML). Long procedures are restructuring by folding portions of the code into sections. Innovative ideas, critical technical knowledge, algorithmic solutions, and unusual coding constructions are clearly documented.

Literate programs are written to be read by other software developers. Program comprehension is a key activity during corrective and perfective maintenance. High quality documentation facilitates program modification with fewer conceptual errors and resultant defects. The clarity of literate programs enables team members to reuse existing code and to provide constructive feedback during code reviews.

Organization of source code into small sections. The style of literate programming combines source code and documentation into a single source file. Literate programs utilize sections which enable the developer to describe blocks of code in a convenient manner. Functions are decomposed into several sections. Sections are presented in the order which is best for program comprehension. Code sections improve on verbose commenting by providing the ability to write descriptive paragraphs while avoiding cluttering the source code.

Production of a book quality program listing. Literate programming languages (CWEB) utilize a combination of typesetting language (TeX) and programming language (C++). The typesetting language enables all of the comprehension aids available in books such as pictures, diagrams, figures, tables, formatted equations, bibliographic references, table of contents, and index. The typographic processing of literate programs produces code listings with elegantly formatted documentation and source code. Listings generated in PDF format include hypertext links.

Remember the Basics. There are many factors involved in developing excellent software. Literate programming is just a single technique to be used along with all the other well established software engineering practices. Here are some software practices related to program documentation:

• Establish structures, processes, and outcomes (see Luke Holman).
• Generate software requirements and design description (see IEEE standards).
• Practice object oriented design.
• Choose class names, function names, and variable names wisely.
• Avoid duplicate code by creating shared functions.
• Re-think or refactor code which is difficult to understand.
• Develop small classes and small functions when feasible.
• Keep it simple and straight forward as much as possible.
• Organize large source code files using an outlining editor (Leo).
• Comment source code effectively with header and in-line comments.
• Document source code using an API documentation standard (doxygen).
• Utilize pre-conditions and post-conditions using assertions.
• Provide formal or informal proofs of source code correctness.
• Conduct peer reviews of deliverables.
• Implement automated unit testing which is also a form of documentation.
• Examine source code metrics (lines, complexity, etc).
• Execute static analysis for common coding errors.

• Неплохое описание про doxygen http://habrahabr.ru/post/252101/, штука слишком развесиста для меня, конечно. У меня orgmode есть. :)
• https://sourceforge.net/projects/pywebtool/ и http://pywebtool.sourceforge.net/
• http://www.literateprogramming.com/
• http://anton-nazarov.livejournal.com/60347.html - в комментариях занятно про идеологию literate programming. Особенно, наверное, http://anton-nazarov.livejournal.com/60347.html?thread=497339#t497339
• https://habr.com/ru/articles/752384/ - пример, как с оргмодом писать настройки exim.
• https://howardism.org/Technical/Emacs/literate-writ-large.html – чел делится опытом жизни. English.