OberonCore

Допустим, до разработки кода сначала формируется документ с требованиями (спецификация), а на основе требований пишется код. Часто бывает, что сначала требования и код практически соответствуют друг другу (и то не полностью), а со временем, например, по прошествии 10 лет, код постепенно эволюционирует в какую-то сторону, а требования (спецификация) уже практически не отражают текущее состояние программы.

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

Обычно на фирмах использут нечто атлассиановское. В исходниках вставляется урла на документ или его код в системе.
В случае ЧЯ+КП можновставлять полноценную ссылку в сам исходный код.

Есть системы управления требованиями типа Cradle, которые встраивают в жизненный цикл софта. Вместо ТЗ - набор требований с привязками. И на этапе реализации в коде делают ссылки на СУТ. Устранение багов тоже со ссылками и коммиты тоже. Это все увязывается с svn, redmine, bugzilla или аналогами.

У нас на "эуропейской" фирме было три типа документов:
- user needs (первоначальный набор требований без какой-либо конкретики);
- techical requirments ("Для того что-бы удовлетворить UN#XXX сделать то-то и то-то");
- software specification ("В программе сделано вот это, т.к. требовалось TR#XXX").
Как-то так в общих чертах

Принципиально никак. Можно только подставлять костыли то там, то здесь.

Попробую объяснить свою мысль. Я всегда говорю, что программирование это процесс формализации концепций предметной области. Требования это описание концепций на неформальном, бытовом языке. Программист должен преобразовать неформальное описание в формальный текст программы, который верифицируется абсолютным исполнителем, т.е. компьютером.
И здесь мы натыкаемся на вечное противоречие между неформальным и формальным, которое постоянно хотят запечатать серебряными пулями. Ведь с требованиями работают живые люди, не компьютеры. Если вы выразите требования формально, да так, что можно автоматически отслеживать их соответствие коду, то программист станет не нужен. В общем-то, это и есть работа программиста.

Можно только фрагментарно, вручную, частным образом протаскивать формальные элементы на концептуальный уровень. Конкретные решения тут уже перечислили, но это всё равно костыли, не снимающие главного противоречия между предметной областью и формальным компьютерным исполнителем.

Используйте ИС Дракон.

При программировании в среде ИС Дракон требования прикладной область неразрывно связаны с программным кодом. В иконе имеются ряд текстовых полей для описания прикладной области и программного кода. Прикладная область описывается на нескольких уровнях.

Обнаружена реклама

Поправьте меня, если я неправ...
Дракон как-то описывает структуру сущностей и отношения между ними в предметной области?

Вот так:
https://ru.wikipedia.org/wiki/Shakespeare_(%D1%8F%D0%B7%D1%8B%D0%BA_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F)

А если серьёзно, пока не будет встроен формальный верификатор в Microsoft Word для людей которые пишут ТЗ (по последним данным, это не тех.задание, а точка зрения ) до тех пор никаких сдвигов не произойдёт, а если такой анализатор будет создан и встроен, то половина программистов сразу должна написать для формальных схем из Word интерпретаторы для своих экосистем, а вторая половина освободится от CRUD-рутины изаймётся написанием следующего поколения программ, сущностно-онтологических.

Можно описывать в текстах произвольной структуры.
Производится декомпозиция описания проблемной области.
Алгоритмы проблемной области размещаются в Дракон-схемах, т.е. в графах логики выполнения.
Дракон-схемы в ИС Дракон содержат алгоритм в терминах проблемной области и языка программирования.

Установлена жесткая связь текста элемента описания прикладной области и соответствующего программного кода.

В других реализациях Дракона присутствует только проблемное описание или только программный код.

В части Данные: Ввод, Хранение, Передача и Обработка Данных помогает заранее подготовленный сквозной тест и его описание. Этот тест будет меняться по мере понимания клиента, что ему нужно в итоге.

Rifat,
на CPC есть

http://www.zinnamturm.eu/downloadsDH.htm#Frame
Пересекается это с вашим запросом?

Не знаю. Скорее мне хотелось бы узнать мнение людей, которые им пользовались. А если никто не пользовался, то когда время будет, надо будет посмотреть.

Сейчас пришла идея, что идея Кнута про грамотное программирование (aka литературное программирование) - это как раз то, что я ищу. В принципе, я согласен с идеей, но насчет реализации надо еще подумать как это лучше реализовать, возможно, стоит реализовать по-другому, чем это было реализовано в системе WEB.

Насколько я понимаю система Кнута позволяет описывать то, что делает код на одном уровне детализации. Вообще выделяют 3 уровня требований:

То есть было бы хорошо, если бы можно было на основе литературного программирования сгенерировать только высокоуровневый документ, который в общих чертах расскажет, что должен делать код. Или же чтобы можно было сгенерировать системные требования (уже более детальные) с описанием основных функций и ограничений или же сгененировать проектную системную спецификацию, которая будет содержать все детали реализации (например, какой параметр в базе чем управляет, какие у него могут быть значения и так далее). Еще, конечно, было бы удобно генерировать пользовательскую документацию тоже. То есть по идее из одного "исходника" надо генерировать 4 разных документа. Не знаю позволяет ли это делать система Кнута.

Это можно доксигеном делать. Только комменты в коде писать.

Доксиген он больше предназначен для создания документации по коду. Обычно он генерирует документацию, содержащую описание классов и их методов. Но при этом может не быть общей информации о том, что мы реализовать то хотели, зачем создали именно такие классы, какие идеи положены в основу. Я бы назвал это кодоцентричным подходом.
У Кнута же скорее противоположный подход, он как бы начинает писать статью и делает вставки кода. А специальная утилита генерирует полный код программы из кусочков. Это я бы назвал документоцентричным подходом.
В любом случае для описания документации необходим один порядок следования мыслей, а для написания кода другой.
То есть хотелось бы найти какой-то промежуточный подход.

Вообще, если проанализировать возможные варианты, то видятся следующие варианты:
1) Есть единый источник, из которого генерируется код и документация (подход Кнута и другие подходы)
2) Код и документация врозь (как это обычно и бывает).
3) Есть код, документация и дополнительный источник, который содержит связи между кодом и документацией.

Мне кажется, что для того, чтобы документация и код были согласованы между собой, то лучше подходит первый вариант. Но там тоже могут быть различные варианты. Например, насколько я понимаю, у Кнута из единого источника генерируется код и один документ. А как быть, если надо генерировать сразу несколько документов, допустим, спецификацию требований и руководство пользователя?