Грамотное программирование

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

Если вы пытаетесь преобразовать свою команду разработчиков, им может быть легче принять этот подход, чем полноценную грамотную методологию, они по-прежнему довольны тем же кодом, но им нужно писать лучшую документацию, встроенную в код.

Это лучшее, что я могу предложить: посмотрите, что ваша команда думает об этой идее.

Единственный неэзотерический язык, который я знаю, который на самом деле поддерживает LP, - это Haskell, и, честно говоря, я не слышал большого спроса на LP в современных языках программирования. Большинство людей довольны использованием встроенных форматов документации (javadoc, rdoc и т. д.)

Мои извинения. Я должен был упомянуть, что мы уже используем Doxygen со скриптом автоматической сборки документов. Мы используем теги .NET doc там, где это возможно, а там, где теги .NET XML doc не хватает, мы добавляем теги doxygen. Это неплохо работает. Дело в том, что при написании документации производительность значительно снижается: мы (люди) очень плохо умеем создавать документацию без какого-либо редактора WYSIWYG. Не говоря уже о чувствительности к ошибкам.

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

Думаю, здесь есть рынок для плагина VS, который это делает.

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

Престижность вам за попытку улучшить работу вашей команды. Пока вы пытаетесь это делать, у вас есть преимущество перед теми, кто этого не делает.

Однажды я использовал «Грамотное программирование» для проекта. Это было действительно сложно, и результаты были действительно хорошими. Казалось разумным компромиссом.

Однако сегодня я предпочел бы использовать другой подход: вместо прозы для людей и кода для машин я бы предпочел написать настолько ясный код, что люди не прочь его прочитать. Когда мне хочется написать комментарий, я думаю: «Я мог бы сделать этот код более понятным». Это означает, что я пишу меньше документации, а не больше.

Что ж, удачи на любом пути, который вы выберете.

+1 за попытку улучшить работу вашей команды

-1 за тупиковый путь

при всем уважении к Knuth, юнит-тесты лучше документации

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

Я не знаю ни одного современного инструментария для грамотного программирования. Я занимался веб-программированием 15 лет назад.

Doxygen - хороший инструмент, но с LP совсем не помогает. Проблема в том, что LP фокусируется на написании кода для чтения людьми. Нет хорошей поддержки для последовательного уточнения / раскрытия. LP нуждается в представлении исходного кода, который имеет другую структуру, чем атрибут / метод класса-файла в VS. NSpec может быть несколько лучше, но тоже слишком восходящий.

Здравствуйте, авторы романов!

Как кто-то упомянул здесь DOxygen: хотя это не позволяет реальный Грамотное программирование(как пример ограничений, это не позволяет изменить порядок просмотра источников), тем не менее, он, кажется, признан ценным инструментом в этой области его собственными защитниками (Защитники LP): он упоминается прямо вверху этой справочной страницы о LP инструменты: Грамотные инструменты программирования

Основная идея грамотного программирования - писать программы в виде математических текстов. Можно как можно яснее определить, что означает каждая концепция, необходимая в программе, затем объяснить, как она реализована на языке и почему кто-то решил сделать это именно так, а не иначе, или что будет изменено позже.

Изменения также можно задокументировать, прокомментировав изменяемый фрагмент кода и вставив новый с объяснением причины изменения. Некоторые изменения могут зависеть от преобразований кода для оптимизации его производительности. Например, создание одного цикла вместо двух в каком-то C-подобном языке, изменение одного выражения на более простое и т. д. Или что-то более сложное, например изменение другой структуры данных для представления информации. Каждое изменение хорошо обосновано и задокументировано. О проблемной области программы можно понять, просто прочитав исходный код, глубоко разобравшись в нем. Избегайте ошибок из-за неясностей. Генезис программы полностью задокументирован, все можно вспомнить позже, потому что каждая мысль заложена в программе.

Строго говоря, грамотные программы с простым текстом можно писать, если программа разработана, но набор ее в TeX / LaTeX - самый эстетичный, функциональный и самый простой способ, потому что разметку LaTeX несложно разместить в большинстве языков программирования.

Написание грамотных программ на Haskell естественно, потому что сценарий Haskell содержит набор объявлений, а не инструкций. Вы можете размещать все объявления в любом порядке. Это отличается от других языков, где важно упорядочить инструкции определенным образом.

Я не использовал ни веб, ни cweb, ни аналогичные программы, но эти программы помогают набирать программы в логическом порядке для человека, тогда как программные модули могут быть сгенерированы для правильной компиляции.

Существует пакет LaTeX под названием listings, который прост в использовании, вы можете запускать каждый фрагмент кода, закрывая комментарий, и заканчивая кодом, открывая новый комментарий, насколько я помню, примерно так:

% /* 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 как ключевые слова для замены пробелами в дополнительных определениях для пакета listings. См. Документацию по пакету.

в конце исходного кода LaTeX просто введите:

% end of literate program */ 

что является комментарием в LaTeX в начале можно поставить обратное:

% /* start of program

Удаление знака комментария% LaTeX, когда вы хотите скомпилировать программу, и его повторная установка при компиляции с помощью LaTeX.

Если вы никогда раньше не использовали LaTeX, вы можете сначала начать с обычного текста. Возможно, комбинируя его с doxigen, чтобы все проиндексировать. Doxigen не нужен с LaTeX, потому что это система набора, где вы можете создавать несколько указателей, гиперссылок, структурировать документацию как книгу.

Программы на Haskell обычно пишутся грамотно. Может быть, было бы неплохо просмотреть какую-нибудь книгу или статью, чтобы увидеть ее.