Как сохранить код и спецификации в синхронизации? - там хорошие [закрытые] инструменты

Нет. Нет счастливой середины. У них разные аудитории и разные цели.

Вот что я узнал как архитектор и составитель спецификаций: Спецификации не имеют долгосрочной ценности. Преодолей это.

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

Части спецификации - в частности, обзоры - могут иметь долгосрочную ценность.

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

Что хорошо работает, так это использование комментариев, встроенных в код, и инструмент для извлечения этих комментариев и создания текущей оперативной документации. Java делает это с помощью javadoc. Python делает это с помощью epydoc или Sphinx . C (и C ++) используют Doxygen . Есть много вариантов: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Обзоры должны быть взяты из исходных спецификаций и помещены в код.

Должен быть извлечен окончательный документ. Этот документ может заменить спецификации, используя обзоры спецификаций и детали кода.

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

Я думаю, что вики-страницы, не относящиеся к Sharepoint, хороши для поддержания документации в актуальном состоянии. Большинство нетехнических людей могут понять, как пользоваться вики, и большинство программистов будут более чем счастливы использовать хорошую вики. На мой взгляд, вики и системы управления документацией в Sharepoint неудобны и неудобны в использовании.

Mediawiki - хороший выбор.

Мне очень нравятся вики, потому что они, безусловно, самые легкие в использовании и сохранении вверх. Они обеспечивают автоматический контроль версий и обычно очень интуитивно понятны для всех. Многие компании захотят использовать для этого Word, Excel или другие типы документов, но ключевым моментом является обеспечение доступа ко всему онлайн и через общий интерфейс.

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

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

Такой подход, безусловно, будет поддерживать синхронизацию спецификации и кода, и тесты будут терпеть неудачу, когда они выйдут из синхронизации.

При этом во многих проектах приведенное выше является добрым пирога в небе. В таком случае С. Лотт прав, переживи это. Они не t оставаться в синхронизации. Взгляните на спецификацию как на дорожную карту, предоставленную разработчикам, а не на документ о том, что они сделали.

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

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

тогда в проекте должно быть определенное время, выделенное для записи (или переписывания) спецификации после написания кода. Тогда он будет точным (до тех пор, пока код не изменится).

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

тогда в проекте должно быть определенное время, выделенное для записи (или переписывания) спецификации после написания кода. Тогда он будет точным (до тех пор, пока код не изменится).

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

Я не знаю особо хорошего решения для того, что вы описываете; в общем, единственные решения, которые я видел, которые действительно синхронизируют такие вещи, - это инструменты, которые генерируют документацию из исходного кода (doxygen, Javadoc).

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