Основная идея грамотного программирования - писать программы в виде математических текстов. Можно определить, что означает каждое понятие, необходимое в программе, настолько четко, насколько это возможно, а затем объяснить, как это реализовано в языке и почему кто-то решил сделать это таким образом, а не каким-либо другим или что будет изменено позже.
Изменения также могут быть задокументированы путем комментирования фрагмента кода для внесения изменений и добавления нового, объясняющего причину изменения.
Некоторые изменения могут зависеть от преобразования кода для оптимизации его производительности. Например, сделать один цикл вместо двух циклов в некотором C-подобном языке, изменить одно выражение на более простое и т. Д. Или что-то более сложное, например, изменить другую структуру данных для представления информации.
Каждое изменение хорошо обосновано и задокументировано.
О проблемной области программы можно понять, просто прочитав исходный код, глубоко поняв его. Как избежать ошибок из-за неясностей.
Генезис программы полностью задокументирован, все можно вспомнить позже, потому что каждая мысль есть в программе.
Строго говоря, можно писать грамотные программы с простым текстом, если программа разработана, но набор текста в TeX / LaTeX является наиболее эстетичным, функциональным и простым способом, потому что нетрудно поместить разметку LaTeX в большинство программ. языки.
Естественно писать грамотные программы на Haskell, потому что скрипт на Haskell содержит набор объявлений, а не инструкций. Вы можете разместить все объявления в любом порядке. Это отличается в других языках, где важно упорядочить инструкции определенным образом.
Я не использовал ни web, ни cweb, ни подобные программы, но эти программы помогают набирать программы в логическом порядке для человека, тогда как программные модули можно генерировать для правильной компиляции.
Существует пакет LaTeX, называемый списками, который прост в использовании. Вы можете начинать каждый фрагмент кода, закрывая комментарий и заканчивая кодом, открывая новый комментарий, насколько я помню, что-то вроде этого:
% /* begin of literate program
\documentstyle{article}
\usepackage{listings}
\lstdefinitions here I do not remember the syntax. Here one can define
a replacement for startcode*/ and /*endcode for spaces.
more definitions here
\begin{document}
Your explanation including formulas like $s=c\times\sum_{i=0}^{i=N} x_i$ etc.
\begin{lstlising}
startcode*/
s=0
for(i=0;i<=N;i++) s=s+x[i];
s=c*s;
etc..
/*endofcode
\end{lstlisting}
More explanation ...
\end{document}
% end of literate program */
в преамбуле текста вы можете определить startcode * / и / * endofcode как ключевые слова для замены пробелами в дополнительных определениях для пакета листингов. Смотрите документацию к пакету.
в конце источника LaTeX просто введите:
% end of literate program */
который является комментарием в LaTeX
в начале вы можете разместить противоположное:
% /* start of program
Снятие знака комментария% LaTeX, когда вы хотите скомпилировать программу, и установка его снова при компиляции с помощью LaTeX.
Если вы никогда раньше не использовали LaTeX, вы можете начать с простого текста.
Может быть, в сочетании с doxigen, чтобы проиндексировать все.
Doxigen не нужен с LaTeX, потому что это система набора текста, где вы можете создать несколько индексов, гиперссылок, структурировать документацию как книгу.
Программы на Haskell обычно написаны в грамотном стиле. Может быть, это хорошая идея, чтобы просмотреть какую-то книгу или статью, чтобы увидеть ее.