Основные элементы программной документации
2.3. пример оформления задачи
Задание
Напишите программу, выполняющую кодирование входной строки перестановкой символов по правилу 2-3-1.
Первый этап работы
Соображения
Необходимо представить себе поведение программы в целом. Хотим ли мы получить программу кодирования одной единственной строки, или желателен диалоговый режим управления кодированием группы строк, каждая из которых вводится после некоторого приглашающего сообщения? Из общих соображений простоты общения и проверки работоспособности второй вариант (циклический ввод) представляется более предпочтительным.
Выводы
Первый раздел требований (спецификации) может быть сформулирован так:
1. Общее описание задачи.
Необходимо разработать программу, выполняющую ввод и преобразование строки символов путем их перестановки по правилу 2-3-1. Программа должна обрабатывать строки последовательно, каждый раз предупреждая пользователя о необходимости очередного ввода.
Соображения
Теперь необходимо принять решения по основным позициям внешнего проекта программы.
- Что такое входная строка (последовательность символов, ограничения на входной алфавит)?
- Существенно ли деление строки на слова (пробел как спецсимвол алфавита, разделитель/ограничитель слов)?
- Может ли в строку (в слово) быть включен символ, не имеющий адекватного представления на клавиатуре, или символ-разделитель как часть слова?
- Существует ли ограничение на длину строки?
- Как вводится входная строка (ограничитель строки и признак конца ввода)?
- Как выходная (преобразованная) строка сопоставляется с входной (формат вывода)?
- Как производится преобразование при длине входной строки, не кратной трем?
Каждый автор может принять собственное решение по этим пунктам. В любом случае свои решения в рамках лабораторного практикума необходимо согласовать с преподавателем.
Выводы
В данном варианте предлагается несколько усложненный вариант требований, предполагающий разбивку строки на слова и выполнение заданных правил перестановки только в пределах отдельного слова. В нем не накладывается сложных ограничений на разделитель слов. Им может быть многоточие или произвольная последовательность точек, запятых и пробелов.
2. Внешний проект.
2.1. Вход.
2.1.1. Входная строка должна вводиться с клавиатуры после вывода на экран приглашающего сообщения.
2.1.2. Входная строка представляет собой последовательность слов, разделенных (ограниченных) символами-разделителями ","; "."; " " (запятая, точка, пробел). Признаком конца ввода строки с клавиатуры является нажатие клавиши "Enter". Длина строки не должна превышать длины строки экрана (80 символов).
2.1.3. Слово входной строки может состоять из букв (русского и латинского алфавита) и/или цифр.
2.1.4. Первому слову в строке может предшествовать последовательность пробелов.
2.1.5. Признаком конца слова является любой символ-ограничитель (см. 2.1.2). Последнее слово строки может не иметь за собой ограничителя.
2.1.6. Ввод пустой строки является указанием пользователя на необходимость закончить работу программы.
2.2. Вывод.
2.2.1. Сообщения программы. Сообщения программы выводятся с новой строки. Курсор после вывода устанавливается на новую строку.
2.2.1.1. "Введите строку для кодирования" - приглашающее сообщение программы. Указывает на необходимость ввода с клавиатуры входной строки.
2.2.1.2. "Работа закончена" - завершающее сообщение программы. Выводится после ввода пустой строки. Работа программы заканчивается.
2.2.1.3. "Ошибка во входной строке" - информационное сообщение программы. Выводится после ввода входной строки, не соответствующей пункту 2.1. Работа программы продолжается с ввода новой строки.
2.2.2. Результат.
2.2.2.1. Выходная строка представляет собой последовательность преобразованных слов, организованную (в смысле разделителей и ограничителей) идентично входной строке.
2.2.2.2. Преобразованные слова выходной строки получаются из соответствующих слов входной строки применением к ним процедуры кодирования.
2.2.2.3. При выводе на экран выходная строка располагается строго под входной (разделитель под разделителем, слово под словом).
3. Функция преобразования.
3.1. Преобразование входной строки. Преобразованию подвергаются только правильные строки.
3.1.1. Преобразование слов входной строки производится путем перестановки каждой тройки символов слова в порядке 2-3-1.
3.1.2. Если в слове количество символов не кратно трем, то преобразование последних символов слова должно производиться по сокращенной схеме.
3.1.2.1. Последние два символа переставляются в порядке 2-1.
3.1.2.1. Единственный последний символ слова остается на своем месте.
3.1.3. Символы-разделители (ограничители) слов остаются в выходной строке на тех же местах, которые они занимали во входной строке.
3.2. Контроль входной строки.
3.2.1. Входная строка считается правильной, если она соответствует требованиям, описанным в пункте 2.1.
3.2.2. Если обнаружено, что входная строка не соответствует пункту 2.1, то на экран (в стандартный поток вывода) должно выдаваться сообщение пункта 2.2.1.3 и снова должен запрашиваться ввод входной строки.
3.3. Вывод результата.
3.3.1. Перед ожиданием ввода строки программа должна вывести на экран (в стандартный поток вывода) сообщение пункта 2.2.1.1 и перевести курсор на новую строку для ввода строки.
3.3.2. Выходная строка должна выводиться строго под входной строкой.
3.3.3. После ввода пустой входной строки программа должна вывести на экран (в стандартный поток вывода) сообщение пункта 2.2.1.2 и завершить свою работу.
4. Требования по проверке функций программной реализации.
4.1. Проверить, что при правильном вводе строки производится ее преобразование в соответствии с п.п. 3.1.
4.1.1. В том числе проверить, что правильно обрабатывается строка, начинающаяся с пробелов.
4.1.2. В том числе проверить, что правильно обрабатывается строка, содержащая слова, длина которых не кратна трем.
4.1.3. В том числе проверить, что правильно обрабатывается (остается без изменения) строка, состоящая из одних разделителей.
4.2. Проверить, что при вводе пустой строки производится вывод сообщения п.п. 2.3.2 и выполнение программы заканчивается.
4.3. Проверить, что выводится сообщение п.п. 2.3.3 и повторяется приглашение к вводу как реакция программы на неправильный ввод строки.
4.3.1. Строка содержит символы, отличные от пробелов, перед первым словом.
4.3.2. В строке встретился недопустимый символ алфавита (недопустимый разделитель слов или недопустимый символ в слове).
4.3.3. Длина строки превышает 80 символов (не считая признака конца строки).
4.4. Проверить, что выходная строка располагается с начала строки экрана и строго под значением входной строки, в том числе при длине строки, строго равной 80 символам.
Замечания
В данном варианте требования по проверке функций программной реализации сгруппированы в соответствии с описанием интерфейса (раздел спецификации 2). В некоторых случаях удобнее разрабатывать и структурировать требования по проверке в соответствии с описанием функций проектируемой системы (раздел спецификации 3).
Второй этап работы
Соображения
Работа над программной реализацией должна начинаться с проектирования основной последовательности действий и/или основных информационных объектов, подлежащих обработке. Последнее предпочтительней, так как дает хорошее основание к модульной декомпозиции программы. Если проще представить себе процедурную форму описания, то, записав последовательность проектируемых действий в виде предложений естественного языка, можно затем проанализировать глагольные группы и существительные. Существительные, особенно подлежащее, часто являются хорошими кандидатами для информационных объектов. Глаголы - кандидаты в процедуры (операции над объектами). Например, в нашем случае:
- (1) ввести входную строку;
- (2) если строка пустая, то закончить работу;
- (3) преобразовать входную строку;
- (4) вывести преобразованную строку;
- (5) ввести очередную входную строку и вернуться к действию (2).
Даже самый простой предварительный анализ подобного описания позволяет нам выделить основной объект "входную строку" и список действий: "ввести", "преобразовать", а также операцию "проверка состояния - строка пустая". Если продолжать декомпозицию дальше, то легко можно выделить объект "сообщение" и соответствующую ему операцию "вывести". Конечно, многие проектные решения определяются программистом на основании его собственного опыта, интуиции, но во всех случаях рекомендуется рассматривать и оценивать несколько вариантов. Например, форма представления строки - список в связном представлении или массив; параметр процедуры "вывести сообщение" - текст сообщения или его номер и т.п.
Выводы
Конечно, все сказанное выше применимо только при разработке достаточно простых задач, объем документации которых не превышает нескольких десятков страниц. В случае выполнения коллективной работы над большим программным комплексом (десятки и сотни тысяч строк программного кода) должны применяться более сложные процедуры и приемы организации и хранения документации, взаимодействия разработчиков.