Для тех, кто еще не знает, зачем пишутся спецификации- http://russian.joelonsoftware.com/PainlessSpecs/1.html
Для тех кому лень- вкратце это выглядит так:
Наиболее важная функция спецификации – проектирование программы (design the program). Даже если вы работаете один, и пишете спецификацию исключительно для себя, процесс ее написания – описание того, как работает программа до мельчайших подробностей – заставит вас непосредственно проектировать программу.
Спецификации сокращают информационные потоки. Когда вы пишете спецификацию, вы должны только один раз выяснить, как программа работает. Каждый член команды может потом просто почитать спецификацию и выяснить интересующие его моменты.
Без детальной спецификации невозможно составить план. Отсутствие плана не проблема, если вы пишете кандидатскую диссертацию и рассчитываете за ближайшие 14 лет ее закончить, или если вы программист, работающий над следующей версией игры Duke Nukem (мы выпустим ее, когда все будет готово и сделано на высшем уровне). Но почти в любой отрасли реального бизнеса вы просто обязаны знать, как долго все будет продолжаться, потому что разработка продукта стоит денег. Вы даже джинсы себе не купите, не узнав, сколько они стоят, так как же ответственный бизнесмен может принять решение, создавать или не создавать продукт, без информации о том, сколько это займет времени, и, следовательно, сколько это будет стоить?
Написание спецификации – прекрасный способ точно выразить все раздражающие вопросы разработки, большие и маленькие, которые захлестнут вас, если у вас нет спецификации.
Спецификации – это мать всего!
Теперь непосредственно о форме и содержании:
(за основу взят шаблон "A Software Design Specification Template" by Brad Appleton. найти можно здесь: http://www.cmcrossroads.com/bradapp/docs/sdd.html)
Введение:
Завершенная спецификация на ПО должна отвечать следующим критериям:
Она должна быть в состоянии адекватно служить в качестве учебного материала для новых участников проекта, давая им достаточно информации и понимания о ходе реализации проекта, с тем чтобы они могли понимать, что говорится о дизайне на собраниях и не почувствовать себя так, как будто они "тонут", когда им впервые предложат создать или изменить исходный код.
Она должна служить "объективным доказательством" того, что дизайнеры и/или программисты выполняют свои обязательства по реализации функций, описанных в спецификации требований.
Она должна быть как можно более подробной, но в то же время не быть слишком обременительной для дизайнеров и/или разработчиков, то есть не становится слишком трудной для создания и поддержки.
Схема шаблона:
Введение;
Обзор системы;
Вопросы проектирования:
-Предположения и зависимости;
-Основные ограничения;
-Цели и руководства;
-Методы разработки;
Архитектурные стратегии:
Стратегия-1 название или описание;
Стратегия-2 Название или описание;
...
Архитектура системы:
Компонент-1 Название или описание;
Компонент-2 Название или описание;
...
Политики и правила:
policy/tactic-1 название или описание;
policy/tactic-2 название или описание;
...
Детальное описание системы:
Модуль-1 Название или описание;
Модуль-2 Название или описание;
...
Глоссарий;
Библиография.
Порядок разделов этого документа соответствует порядку, в котором должны рассматриваются вопросы проектирования, и в котором принимаются решения в ходе самого процесса проектирования. Конечно, понятно, что проектирование программного обеспечения часто (а зачастую и к счастью) не всегда происходит в таком порядке (или в любом линейном или даже просто в предсказуемом порядке). Однако полезно для понимания структуры системы, представить их, как если бы они были сделаны так.
Рекомендуется сохранять все обсуждения принятия тех или иных решений (в том числе истории переписки, логи и т.д., так как они являются единственным достоверным источником информации о принятых решениях).
Далее по разделам:
Введение:
Предоставление обзора всего документа:
-описание назначения дока;
-границы\область действия;
-целевая аудитория;
-определение системы, используя подходящие имена, версии и т.д.;
-ссылки на другие используемые документы;
-взаимосвязанные документы;
-предпосылки;
-документы, описывающие фреймворк;
-документы, которые будут писаться на основе этого документа;
-определение важных понятий, сокращений, аббревиатур;
-краткое содержание.
Обзор системы:
Дать общее описание системы, включая ее функциональность и вопросы, связанные с системой в целом и ее структурой (возможно, в том числе обсуждение основных подходов к проектированию и организации). Вы можете разделить это описание на подразделы и тд.
Вопросы проектирования:
В этом разделе описываются многие из вопросов, которые должны быть заданы или решены, прежде чем пытаться разработать комплексное решение дизайна. -предположения и зависимости:
Похожие программное или аппаратное обеспечение;
Операционные системы;
Характеристики конечного пользователя;
Возможные и/или вероятные изменения в функциональности. -основные ограничения:
HW и SW окружение;
окружение конечного пользователя;
наличие ресурсов;
соответствие стандартам;
требования совместимости;
требования интерфейсов и протоколов;
требования БД и транспортов;
требования безопасности;
ограничения памяти и производительность;
быстродействие;
сеть;
требования тестирования, тестопригодность;
другие значения требований качества;
другие требования. -Цели и руководства:
описываются любые цели, правила, руководства, приоритеты, которые влияют на структуру системы. Такие цели могут быть такими:
(Сохранить это максимально простым и понятным;
(акцент на скорости работы, вместо ограничения выделения памяти;
(работать, выглядеть, ощущать продукт, как готовый;
Для каждой такой цели пишутся причины ее указания тут и причины принятия (если необходимо- в отдельном подразделе). -Методы разработки:
Краткое описание методов и подходов для проектирования и разработки системы. Если один или несколько официальных/опубликованных методов были приняты или адаптированы- необходимо включить ссылку на более подробное описание таких методов. Если несколько методов, были серьезно пересмотрены, то каждый из таких методов следует отметить, наряду с кратким объяснением того, почему все или часть его используется или не используется.Архитектурные стратегии:
Указываются любые проектировочные решения и стратегии, которые влияют на общую организацию системы и на ее структуру высшего уровня . Эти решения должны дать представление о ключевых вопросах и механизмах, используемых в архитектуре системы. Описываются рассуждения для каждого решения (возможно, ссылаясь на ранее определенные цели и принципы). Описываются причины принятия тех или иных решений, их изменения или отказ от них. Такие решения могут касаться (но не ограничиваются ими) вещей, вроде следующих:
использование частных (сторонних) продуктов и инструментов- язык программирования, БД, библиотеки и т.д.;
повторное использование существующих компонентов системы;
планы на расширение и доработки;
используемые образцы интерфейсов (модели ввода\вывода);
примеры взаимодействия HW, SW;
обнаружение ошибок и восстановление после сбоев;
использование памяти;
внешние БД и СУБД;
распределенные данные и контроль над всей сетью распределения;
основные подходы к контролю;
распараллеливание и синхронизация;
механизмы взаимодействия;
управление другими ресурсами.Каждое значительное решение, вероятно, следует обсуждать в своем собственном подразделе либо (если оно достаточно сложное) в отдельном документе проектирования (с соответствующей ссылкой отсюда, конечно). Убедитесь, что при описании проектного решения вы также обсуждаете любые другие значительные альтернативы, и ваши причины для отказа от них указаны (а также ваши причины для принятия альтернативных решений, которые вы окончательно утвердили к принятию)
Архитектура системы:
Этот раздел должен предоставить общий (высокоуровневый) обзор того, как весь функционал системы был разделен, а затем назначен в подсистемы или компоненты. Не нужно вдаваться в подробности об отдельных компонентах (есть раздел для последующего подробного описания всех компонент). Основной целью является получение общего понимания того, каким образом и почему система разбита на отдельные части, и как отдельные части работают вместе, чтобы обеспечить требуемую функциональность.
На самом верхнем уровне описывается основной функционал. Что программное обеспечение должно выполнять и различные роли, которые система (или некая часть системы) должна играть. Описывается, каким образом эта система была разбита на ее компоненты/подсистемы (с указанием каждого компонента (подсистемы) верхнего уровня и распределения функций, возложенных на него). Описывается, как на более высоком уровне компоненты взаимодействуют друг с другом в целях достижения необходимых результатов. Не забудьте предоставить обоснования для выбора данного разбиения системы (возможно обсуждение других предлагаемых разбиений и описания, почему они были отклонены). Не стесняйтесь использовать шаблоны проектирования либо в описании части архитектуры (в формате шаблона ), либо в виде отдельных элементов архитектуры, которые их используют.
Если есть какие-либо схемы, модели, диаграммы, документированные сценарии или юз-кейсы поведения системы и/или структуры, они могут быть включены сюда (если вы не чувствуете, что они достаточно сложны, чтобы НЕ находиться в подробном разделе "Детальное описание системы"). Диаграммы, схемы описывающие конкретный компонент или подсистему должны быть включены в подраздел, описывающий этот компонент или подсистему.
Примечание: Этот раздел (и его подразделы) на самом деле относится только к новым разрабатываемым (или которые еще предстоит разработать) частям системы. Если есть части системы, которые уже существуют к началу разработки новых, то вам нужно описать только те уже существующие части, от которых новые части системы будут зависеть, и только в достаточной детализации, достаточной для описания взаимосвязей и взаимодействий между старыми и новыми частями. Прежние части, которые были изменены или расширены должны быть описаны лишь в той степени, которая необходима читателю, чтобы получить достаточное понимание характера изменений, которые были сделаны.
Архитектура подсистем:
Если есть какой-то компонент, который заслуживает более подробного обсуждения, чем это было представлено в разделе "Архитектура системы", предусматривается, что более подробное описание будет в соответствующем подразделе раздела "Архитектура системы" (или даже может быть в более подходящем для описания компонента в своем собственном документе). Если необходимо, то опишите, как компонент был разделен на подкомпоненты, а также взаимосвязи и взаимодействия между этими подкомпонентами (аналогично тому, что было сделано для верхнего уровня компонентов в разделе "Архитектура системы").
Если какой-либо подкомпонент считается также заслуживающим дальнейшего обсуждения,- опишите его в отдельном подразделе этого раздела (таким же образом). Добавляйте столько уровней/подразделов, сколько необходимо для того, чтобы читателю получить более высокий уровень понимания всей системы или подсистемы (но не забудьте оставить подробности для раздела "Описание системы").
Если этот компонент является очень большим и/или сложным, вы можете рассмотреть вопрос о документировании его структуры в виде отдельного документа и просто, в том числе, ссылки на него в этом разделе.
Политики и правила:
Описываются любые политики, правила, тактические решения, которые не несут за собой архитектурных изменений. Т.е. они не будут существенно влиять на общую организацию системы и ее структуру высшего уровня, но которые тем не менее, влияют на детали интерфейса и/или осуществление различных аспектов системы. Такие решения могут касаться (но не ограничиваются ими) вещей, вроде этих:
выбор специфических продуктов- компилятор, интерпретатор, БД, библиотеки и т.д;
инженерные компромиссы;
стандарты и правила кодирования;
протоколы подсистем, модулей, процедур;
выбор алгоритмов, паттернов;
планы по обеспечению отслеживаемости реализуемых требований;
планы тестирования;
планы поддержки системы;
нтерфейсы для конечных пользователей, программного обеспечения, оборудования и коммуникации;
иерархическая организация исходников по файлах, директориям, компонентам;
компиляция, сборка и т.д.Каждое конкретное правило или набор правил должны быть вероятно обсуждены в конкретном разделе или (при случае большого или комплексного набора правил) в отдельном документе (с соответствующей ссылкой из этого документа, конечно). Убедитесь, что пока вы описываете решение по архитектуре, дизайну, вы также не забываете рассматривать и описывать альтернативные варианты и причины для отказа от них.
Детальное описание системы:
Большинство компонентов, описанных в разделе "Архитектура системы" потребует более детального обсуждения и описания. Другие компоненты (нижних уровней) и подкомпоненты возможно, необходимо будет также описать . Каждый подраздел этого раздела будет ссылаться или содержать подробное описание программных компонентов системы. В ходе обсуждения должны быть охвачены следующие атрибуты компонентов программного обеспечения:
классификация: вид компонента, такого как подсистема, модуль, класс, пакет, функция, файл и т.д.;
определение: специфическое назначение и значение компонента в системе. Может понадобиться ссылка на спецификацию требований;
функции и поведение компонента: Что должен выполнять этот компонент? Какие роли он играет? Какие виды сервисов он предоставляет для клиентов\пользователей? Для некоторых компонентов здесь может быть необходима ссылка на требования;
Ограничения: Любые уместные ограничения, лимиты для этого компонента. Здесь должны быть указаны ограничения по времени, объему данных, состояниям компонента, может включать в себя правила для взаимодействия с этим компонентом (охватывающие предварительные условия, постусловия, инварианты, другие ограничения на входе или выходе, форматы (типы) данных и доступ к данным, синхронизация, исключения и т.д.);
Состав: описание использования и важности субкомпонентов, которые являются частью этого компонента;
Использование\взаимодействие: описание взаимодействия с другими компонентами. Какие другие компоненты используются этим компонентом? какие используют данный компонент (здесь необходимо включить описание влияния на другие части и компоненты, которое может иметь данный компонент). Объектно-ориентированный дизайн должен содержать описание любых известных или предполагаемых подклассов, суперклассов и метаклассов;
Ресурсы: описание всех управляемых, находящихся под влиянием этого компонента, а также необходимых ресурсов. Ресурсы являются внешними элементами при проектировании, например, память, процессоры, принтеры, БД или библиотеки. Здесь должно быть включено обсуждение всех возможных условий и возможных блокирующих проблем, а также пути их решения;
Обработка: описание того, как компоненты действуют, выполняя функционал, который они должны выполнять. Это должно включать в себя описание всех алгоритмов, изменения состояний; соответствующие временные или пространственные сложности; параллельность, методы создания, инициализации, а также очистку; обработку исключений;
Интерфейсы\экспорт: набор сервисов (ресурсы, данные, типы, ограничения, процедуры и исключения), которые предоставляются этим компонентом. Четкое определение и объявление каждого такого элемента должно быть актуальным, с комментариями и аннотациями, описывающими значения величин, параметров и т.д. для каждого сервиса;
Значительная часть информации, которая появляется в этом разделе не обязательно должна содержаться отдельно от исходного кода. В самом деле, большую часть информации можно почерпнуть из самих исходников (особенно, если они адекватно комментированы). Данный раздел не должен копировать или воспроизводить информацию, которую можно легко получить из чтения исходного кода (было бы нежелательно дублировать усилия, также будет очень трудно быть в курсе послених изменений). Рекомендуется, чтобы большая часть этой информации содержалась в исходниках (с соответствующими комментариями по каждому компоненту, подсистеме, модулю, и подпрограмме). Таким образом, ожидается, что этот раздел будет в значительной степени состоять из ссылок (выдержки из аннотированных схем) и исходного кода.
Глоссарий:
Все участники создания системы должны говорить на одном языке (правильно понимать друг друга). см. пост "заведи себе глоссарий".
Сообщения
