Спецификация (документирование) учебных задач

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

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

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

Первый раздел – это краткое описание конечного продукта (аналог SOW). Описание должно быть достаточно кратким, но давать чёткое понимание назначения продукта. Здесь же следует указывать язык реализации и архитектуру целевой машины, как самые общие требования к реализации. Например, если рассмотреть программу, вычисляющую периметр треугольника по длинам его сторон, то краткое описание может иметь следующий вид.

Программа вычисления периметра треугольника по длинам его сторон. Язык реализации Си. Архитектура – х86.

Во втором разделе рассматривается интерфейс программы. Под интерфейсом понимается все данные, методы и средства предназначенные для взаимодействия с внешними программами, пользователями, периферией (датчиками и исполнительными устройствами). Раздел, описывающий интерфейс всегда удобно рассматривать с трёх точек зрения:

- входы;

- выходы;

- хранимые данные.

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

1) Входы

a. Данные, вводимые с клавиатуры: Три целых положительных числа, меньшие 100 – длины сторон в десятичной системе исчисления.

b. Параметры – данные, передаваемые из среды ОС Нет

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

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

При описании интерфейса часто приходится накладывать ограничения на диапазон входных значений. В случаях, когда это не связано с ограничениями самого типа передаваемых на вход данных, следует обратить внимание на то, что указываемые ограничения справедливы лишь для самого модуля/программы. Они определяют условия, при которых модуль/программа выполнит то, что он должен выполнить. Но в интерфейсе нельзя наложить ограничение на «пользователя», использующего описываемый интерфейс – он может нарушить ограничения и передать любое значение. Обработка таких ситуаций должна быть обязательно учтена и описана в функциональных требованиях.

Третий раздел спецификации описывает функциональные требования к ПО. Здесь должна быть подробно в виде требований описана вся функциональность ПО, включая все особые случаи. Например, в нашем примере переданные числа могут оказаться не сторонами треугольника (не удовлетворять основному правилу треугольника), и необходимо чётко указать, что программа должна делать в таком случае.

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

Требования к ПО должны отвечать на вопрос «что должна делать программа». Следует чётко различать вопросы «ЧТО» должна делать программа и «КАК» она должна это делать. Вопрос «что» – это определение функциональности, а вопрос «как» – это определение алгоритма. Сам алгоритм относится уже к архитектуре системы, за исключением особых случаев, когда требуется реализация конкретных алгоритмов, например, шифрование, расчёт контрольной суммы, но даже в этих случаях следует минимально ограничивать реализацию. Итак, требования к ПО содержат в себе определение функциональности, а алгоритмы и детали реализации – это архитектура ПО.

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

1. Ввод данных.

2. Проверка корректности данных.

3. Расчёт периметра.

4. Вывод результатов (или типа ошибки).

Для каждого функционального подраздела далее формулируются требования. Например, для «проверки корректности данных» можно записать следующие требования:

3.1.1 Программа должна проверить, являются ли введённые три числа длинами сторон треугольника согласно основному правилу треугольника (сумма двух любых сторон треугольника больше длины третьей стороны).

3.1.2 Если введённые числа не являются длинами сторон треугольника, то программа должна выполнить <ссылка на требование 3.4... о выводе сообщения о соответствующей ошибке из раздела 3.4 вывода результатов>.

3.1.3 Программа должна проверить, что каждое из введённых трёх чисел меньше 100 и больше 0.

3.1.4 Если введённые числа не принадлежат интервалу от 0 до 100, то программа должна выполнить <ссылка на требование 3.4... о выводе сообщения о соответствующей ошибке из раздела 3.4 вывода результатов>.

ПРИМЕЧАНИЕ: заметим, чтоконтроль диапазона значений может быть оговорен в функциональном разделе «Ввод данных», тогда здесь он может отсутствовать.

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

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

Обычно удобно начинать тест требование со слов «Проверить, что …». Например, для входов программы расчёта периметра треугольника можно сформулировать следующее тест требование:

Проверить, что если значение одного из входов больше или равно 100, то программа выдаст сообщение об ошибке, указанное в пункте <ссылка на пункт с сообщением об ошибке из раздела 2>.

Заметим, что подобное тест-требование существенно отличается от:

Проверить, что если значение любого из входов больше или равно 100, то программа выдаст сообщение об ошибке, указанное в пункте <ссылка на пункт с сообщением об ошибке из раздела 2>.

Ибо такая формулировка ТРЕБУЕТ, чтобы подобные значения, например 150, были при проверке последовательно заданы для каждой из сторон треугольника, а на самом деле ещё и для всех пар сторон.

Дополнительно тест-требование может задавать некоторый приоритет функций, явно не прописанный в требованиях к программе. Так, например, при входных значениях 1, 2, 100, не вполне ясно какие сообщения должна выдавать программа. О превышении максимальной длины (100) или о невозможности построить треугольник с этими сторонами (1+2<100)? Тест-требование может гласить:

«Проверить, что < описание ситуации >, оба сообщения <ссылка на пункт с сообщением об ошибке из раздела 1 и раздела 2> выводятся программой.»

Составление тестов более подробно рассматривается в Главе 9 данного пособия.

После определения указанных разделов начинается процесс кодирования. Результат – код программы/функции/модуля – тоже может рассматриваться как пятый раздел спецификации. Для сложных программ, рекомендуется начинать это раздел с подраздела 5.1 описания алгоритма в виде блок-схемы или псевдокода, и только потом переходить к подразделу 5.2 — коду программы.

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

По тест-плану пишется тест модуль (тест-драйвер), который автоматически выполняет («прогоняет») все тесты из тест-плана. Задача тест-модуля обеспечить возможность повторяемости тестов после исправления обнаруженных ошибок.

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

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

Дата добавления: 2014-12-26