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

Ответ 1

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

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

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

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

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

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

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

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

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

Ответ 2

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

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

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

Ответ 3

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

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

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

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

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

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

Ответ 4

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

Ответ 5

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