Мы всегда записываем функции или классы, и их логика очень сложна. Если для этих структур нет спецификации, позже нам даже трудно понять идеи.
Как вы пишете спецификации для сложных функций и классов?
Расскажите, пожалуйста, что-нибудь о вашем собственном опыте, но не только о какой-то ссылке, спасибо.
Я нахожу, что самая большая проблема с функциональными спецификациями - это не формат напрямую, а их синхронизация с вещами, которые приводят их (требования) и все, что на них строится (тестовые примеры, документация).
По этой причине я предпочитаю обрабатывать эту проблему с помощью подхода, ориентированного на модель, а не с помощью бумаги.
Я использую инструмент моделирования UML (Enterprise Architect от Sparx Systems, но многие инструменты также работают), чтобы захватить все артефакты проекта в одном месте и создать прослеживаемость между ними. В Enterprise Architect я могу создать прослеживаемость от артефакта требований к артефакту дизайна (например), просто поставив их на одной диаграмме и создав коннектор от одного к другому с помощью перетаскивания мышью.
Моя "функциональная спецификация" на самом деле представляет собой набор диаграмм действий, по одному для каждого случая использования в системе. Каждый случай использования связывается с одним или несколькими требованиями, которые требуют этого варианта использования. Даже конечным пользователям достаточно легко следовать диаграммам деятельности и проверять их (насколько легко заставить конечных пользователей читать, а тем более понимать и проверять традиционную функциональную спецификацию на бумажной основе?)
Аналогичным образом я могу создать прослеживаемость из диаграмм активности (случаев использования) для конкретных артефактов дизайна, таких как диаграммы классов.
QA может моделировать тестовые примеры и создавать прослеживаемость из их тестовых случаев в случаях использования. Таким образом, мы видим, есть ли какие-либо варианты использования, которые не имеют тестовых примеров (или не имеют достаточного количества тестовых примеров).
Хорошая вещь в Enterprise Architect как инструменте заключается в том, что все эти артефакты хранятся в базе данных SQL, поэтому я могу просто запускать некоторые запросы, которые я создал с течением времени, чтобы найти артефакты, в которых ничего не отслеживается/из них.
Отъезд Joel on Software. И здесь. И здесь. Там даже реальный пример.
Вы должны сделать исследование по следующим предметам (не обязательно в порядке):
Это наиболее распространенные подходы к спецификации программных проектов.
Я вижу некоторые жалобы выше о ссылках на материал Джоэла, а не в текстовом тексте, поэтому я беру на себя то, что он говорит.
На самых высоких уровнях функциональные спецификации должны сообщать о том, что программа ставит перед потребителем или клиентом. Я на 100% знаком с Joel: английский (ну любой!) Язык, используемый с строгостью, - очень мощный инструмент, который все ваши клиенты будут экспертами по перевариванию. Экспертами в UML они не являются.
Документ функциональной спецификации верхнего уровня (FSD) может обеспечить логическую структуру, которая учитывает требования системы в логической модели, которую люди могут легко понять.
Чистые документы требований - что-то, что предшествует FSD, - это сложная рыба, с которой приходится иметь дело. Очень немногие люди умеют мысленно дифференцировать то, что является требованием, и что является частью решения. Поэтому лучше всего соблюдать требования на очень высоком уровне и, как аналитик, сосредоточиться на FSD.
FSD должна быть полной моделью верхнего уровня системы и последующим процессом проектирования более детальной иерархии моделей. Конечным уровнем детализации является реальный код.
FSD должен содержать набор простых английских утверждений. Используйте один заголовок в документах, сохраняйте парас до двух предложений макс и укажите каждый параграф. Просмотрите парас и убедитесь, что каждый говорит что-то полезное. Если нет, удалите его. Короткие хорошие!
Подумайте очень сложно о языке в вашем FSD. Уточните определения ключевых существительных в своих параграфах. Эти существительные становятся вашими классами. Глаголы, которые вы используете, становятся вашими методами класса. Это действительно настолько просто!
Как говорит Джоэл, напишите вам предложения, как вы собираетесь их компилировать. Например, напишите " Если происходит ситуация , тогда делать больше", а не Если происходит, делать больше "или" делать больше, когда что-то происходит ".
Эти типы письменных моделей могут извлечь выгоду из использования конкретных диаграмм, таких как диаграммы конечного состояния, но остерегайтесь думать, что вы можете захватить систему, используя набор диаграмм UML. Эти вещи просто не являются мощными, гибкими или достаточно строгими, чтобы действовать как полное описание сами по себе. Гораздо эффективнее начинать с наброска, написанного на строгом английском, и при необходимости дополнять это.
Что касается проблем итерации, в идеальном мире вам нужно только переработать более низкие уровни модели. Если вам нужно изменить высокие уровни, что-то серьезное было неправильным. Что касается UML-инструментов, которые быстрей, что позволяло возрождать - мак-петух! Ключ в том, что все эти описания - КРАТКИЙ и КОНЦЕСС. Английский - это путь, потому что мы все так долго практиковали это.
Я видел, как люди проводят день, пытаясь сделать симпатичные диаграммы сущностей похожими на перекрывающиеся линии. Как почему? Является ли ваше окончательное решение двумерными коробками и линиями? Нет! И что проблема с UML: диаграммы становятся самоцелью для аналитика и отключают вас от клиента, а не помогают общаться.