Учебное пособие по курсу «Технология программирования»

Вид материала

Учебное пособие

Содержание 9. Документация и отладка. Список литературы

Подобный материал:

• Курсовой проект по курсу «Технология программирования», 147.33kb.
• Учебное пособие для студентов специальности 260202 «Технология хлеба, кондитерских, 1941.61kb.
• О. М. Мышалова общая технология мясной отрасли учебное пособие, 1355.07kb.
• Учебное пособие Иркутск 2006 Рецензент, 2159.1kb.
• Учебное пособие Иркутск 2006 Рецензент, 2160.36kb.
• Учебное пособие Кемерово 2004 удк, 1366.77kb.
• Учебное пособие Тамбов 2009 удк 339. 138, 1882.57kb.
• А. Ю. Просеков С. Ю. Юрьева технология молочных продуктов детского питания учебное, 4980.6kb.
• А. Н. Петров А. Г. Галстян А. Ю. Просеков С. Ю. Юрьева технология продуктов детского, 2728.08kb.
• Учебное пособие Йошкар-Ола, 2008 ббк п6 удк 631. 145+636: 612. 014., 7797.37kb.

^

9. Документация и отладка.

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

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

Можно, конечно, поспорить с этим утверждением, но если рассмотреть непредвзято, то, скорее всего, мы согласимся с тем, что документирование программы является одним из процессов отладки. В процессе документирования разработчик, описывая алгоритм решения, постановку и уже используемые способы решения задачи, яснее и чётче представляет задачу и таким образом вольно или невольно выполняет обзор задачи и методов её решения/реализации. На этом этапе документирования выполняется сопоставление целей и средств, затраченных на достижение цели. Дело в том, что именно на этом этапе разработчик, чаще всего, начинает задумываться о том, что будет далее с полученным решением. Очень часто и разработчик и заказчик вдруг обнаруживают, что остановились на полпути. То есть, часть решения (обычно самую трудоёмкую его часть) получили автоматизировано, а далее собираются применять стандартные «ручные» технологии, хотя именно теперь, получив решение в электронном виде, следует и далее применять ЭВМ. Но если вы далее собираетесь использовать машину, то почти наверняка, конечный вид результата будет другим. Одно дело, если вы получили отчёт и затем собираетесь «вручную» его обрабатывать: тогда он вам нужен на бумаге. Другое дело, если затем этот отчёт поступит на дальнейшую электронную обработку: тогда, скорее всего, отчёт надо сохранить в виде базы данных, а просмотреть отчёт можно и на мониторе, не выводя его на бумагу, но тогда зачем писать трудоёмкую программу вывода отчёта на печать.

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

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

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

Поэтому, когда вы очень долго отлаживаете некоторое ПО, и оно ни в какую не хочет работать, я всегда рекомендую; «Опишите ваше ПО!». Может выясниться, что вы пытаетесь достичь невозможного или решить задачу, которая не имеет решения. Обратите внимание, что в данном случае документирование ПО выступает как типичный приём отладки, причём приём, который позволяет одновременно видеть и лес и деревья.

В связи с этим возникает не менее двух вопросов: когда писать документацию на ПО и какая она должна быть?

Сначала лучше разобрать вопрос, какой должна быть документация? Чаще всего документация бывает трёхуровневой:

1. Инструкция по использованию программы;

2. Подробная документация для пользователя;

3. Подробная документация для программиста, сопровождающего ПО.

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

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

Конечно, в простых случаях документация может появиться раньше описываемого программного обеспечения, особенно, если программист обладает склонностью к мазохизму (но я таких не встречал). На все остальные реалии практикующий программист возразит, что будете вы переписывать свою документацию ровно столько раз, сколько исправлять описываемую документацией программу, а поскольку реализует программу и описывает её одно лицо, то ясно, что прежде всего идёт реализация программы. Ну не любят программисты описывать свои программы. А зря. Лев Толстой не поленился более двадцати раз переписать «Войну и мир». Документация это лицо вашей программы, это представление вашего труда. Может случиться так, что вашей программой не будут пользоваться, только потому, что она плохо документирована. Не написав документацию, вы фактически недоотладили вашу программу!

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

В последнее время появилась тенденция пытаться не оформлять документацию на программу, ссылаясь на то, что в реализованном продукте есть “HELP”. Мы не оспариваем полезность и необходимость “HELP”a, но никакой “HELP” не заменит хорошей трёхуровневой (или более) документации. Цель “HELP” отвечать на конкретные вопросы по работе с программой, возникающие у пользователя в процессе работы. “HELP” отвечает на вопрос “Как?”, а документация ещё и на вопрос “Почему?”. Кроме того, “HELP” предназначен для пользователя, а не для программиста.

Цель написания документации не только в том, чтобы сделать пользователю ясной работу с программой, но и подробно описать все возможности и ограничения программы. Документация должна быть как можно более подробной. Цель написания документации – “показать”, а не скрыть. Следует отметить, что после знакомства с современной документацией на некоторые программные продукты возникает впечатление, то эти документы формировались именно с целью чего-то скрыть, спрятать, не показать. Особенно это касается документации по Windows. Здесь сторонники закрытого программного обеспечения попались в ловушку. С одной стороны они хотят продавать коробочное ПО, ориентированное на программиста, с другой стороны хотят, как можно больше скрыть. Но современные технологии имеют тенденцию к открытости. например, если вы серьёзно используете некоторые классы, то при работе в Cи++ вам просто необходимы тексты этих классов, а не только их заголовки.

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


0. В любой документации должно быть указано, на какой уровень она рассчитана.

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

Все документы должны иметь предметный указатель. Его отсутствие затрудняет поиск терминов и снижает интерес к документации, а, косвенно, и к вашему ПО.

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


1. Инструкция по использованию программы:

Этот документ отвечает на вопросы “Что?” и “Как?” Здесь должны быть перечислены цели разработки и все возможности программы. Минимальные системные требования должны быть перечислены здесь: сколько надо оперативной памяти, какой тип процессора, какая требуется операционная среда и т.д.

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

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

Основное содержание: подробное описание выполняемых шагов и действий для достижения названых целей. Какую, когда и где нажать кнопку или клавишу. Что делать если будет такое сообщение. Куда обратиться в таком-то случае. Где искать ответ на такие-то вопросы.

“Инструкция по использованию программы” это инструкция для “дурака” – не стесняйтесь писать “По окончании ввода нажмите клавишу «RETURN»”, предварительно, объяснив, где находится эта самая клавиша. Пользователь, читающий этот уровень документации, хочет знать “как”, а “зачем” и “почему” его не интересует. С другой стороны, любой пользователь однажды в жизни проходит этот уровень!

Более того, освоение любой программной среды рекомендуется начинать с чтения документации этого уровня.


2. Подробная документация для пользователя:

Цель этого уровня документации ответить на вопросы пользователя (!) “зачем” и “почему”, а также на некоторые более сложные вопросы, ответа на которые нет в “Инструкции по использованию программы”.

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

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

В “Подробной документации для пользователя” приводится список всех возможных сообщений ПО и необходимые действия пользователя по этим сообщениям. Если сообщение предназначено для программиста его всё равно приводят здесь с пометкой «вызовите программиста сопровождающего ПО».

Взаимодействие с другим программным обеспечением, возможности экспорта/импорта, форматы обрабатываемых данных должны быть указаны.

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

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


3. Подробная документация для программиста, сопровождающего ПО.

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

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

Перечислим, кратко, что надо описать при сдаче открытого ПО, а уж что надо закрыть разработчик определит сам.

Для любой программы необходимо привести:

0. Привести автора программы и время написания программы.

1. Описание реализации: язык и среда программирования и тестирования, а также предполагаемого использования; размеры в байтах (при переменном размере указывается максимальный размер) и размер памяти под данные; размеры программы в операторах; все вызываемые подпрограммы и процедуры;

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

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

2. Если программа является подпрограммой или у программы есть входные параметры: описать типы входных и выходных параметров и последовательность их передачи, а также способ передачи (по ссылке или по значению); описание смысла передаваемых параметров.

3. Описание возвращаемых параметров: их типы и смысл.

4. Описание исключительных ситуаций и реакции программы на них.

5. Описание сообщений программы, если они есть, и рекомендуемые действия по обработке сообщений.

6. Краткое описание алгоритма: если известен автор, привести имя автора; если алгоритм имеет название привести название алгоритма; назвать источник, откуда был взят алгоритм или где приведен текст программы, реализующий алгоритм; кратко описать сам алгоритм (возможно, привести его блок-схему).

7. Список входных и выходных файлов и их организация. Назначение каждого файла. Если используется БД, то какая?

8. Описание структуры записей каждого файла. Описать каждое поле в записи с приведением сведений о длине, типе и назначении поля. Указать наличие ключевых полей и строение индексов, если таковые имеются.


Если вы описываете передаваемый класс, то схема остаётся такой же с точностью до смены терминологии: вы описываете свойства, методы и события. Для каждого свойства вы перечисляете тип, длину, смысл и вид доступа. Методы и события, точнее, обработчики событий, описываются точно так же, как и программы.

Но класс ещё должен быть описан и сам по себе: вам необходимо указать, для чего класс нужен, указать всех предков класса, если таковые имеются, перечислить все дружественные и виртуальные функции, а также все операции класса, если таковые имеются. То есть, если вы перегружаете для класса операцию “+”, то это необходимо указать, особенно, если вы используете знак операции “+” не так как все привыкли.


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

При сдаче готовой технической продукции ничего не скрывается. Почему это должно делаться при сдаче программного обеспечения? Единственное возражение, что на программу распространяется авторское право,. но тогда вы должны не скрывать свой продукт, а наоборот – публиковать его. Что делается в литературе, музыке и т.п.: продукт публикуется! После публикации все знают, кто автор и что он написал, при этом права на публикацию заранее оговариваются. Отсюда ясно, что если заказчик оплатил разработку программного продукта то у него имущественные права на разработку, в том числе и на тексты программ. Авторские права неотъемлемы и остаются за программистом. Таким образом, разработчик обязан сдать все тексты программ заказчику, если нигде не оговорено противное. Классы, часто, просто необходимо приводить вместе с текстом класса.

Тем не менее, существует несколько приятных случаев для любителей скрытия текстов. Тексты программ не сдаются:

1. Если это оговорено заранее с заказчиком;

2. Если в программу вставлено некое авторское “ноу-хау”; то есть, имеется нечто, чего никто кроме автора программ не умеет делать! Обычно, не сдаются тексты, по которым может быть «вычислено» это “ноу-хау”, все остальные тексты при этом всё равно сдаются.

3. Если этого требуют условия конфиденциальности; программа может содержать данные или алгоритмы, по которым прямо или косвенно могут быть вскрыты другие, сугубо конфиденциальные данные;

4. Если это тексты сторонних разработчиков; даже если эти тексты опубликованы, лучше сослаться на публикацию.

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

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

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


Вопросы к главе 9.


1. Можно ли процесс документирования программного обеспечения считать одним из способов отладки.

2. Когда надо писать документацию на сдаваемое ПО?

3. Какой должна быть документация на программное обеспечение.

4. Что надо описать в «Инструкции по использованию программы».

5. Что надо описать в «Подробной документации для пользователя».

6. Что надо описать в «Подробная документация для программиста, сопровождающего ПО».

7. Надо ли сдавать тексты исходных модулей?

8. Перечислите законные основания для сокрытия текста программы.


Законы практического программирования и не только.


1. Программист – программируй.

2. Выигрываешь память – проигрываешь время, выигрываешь время – проигрываешь память: правило рычага в программировании.

3. При увеличении объёма данных на порядок меняется алгоритм доступа к данным.

4. Чем сложнее структуры данных, тем проще программа; чем проще структуры данных, тем сложнее программа.

5. Один час постановки равен пяти часам отладки.

6. Если твоя рука выводит стопятидесятый оператор в программе – бей по ней линейкой.

7. Сначала работающая программа – потом её оптимизация.

8. Сначала работающая программа – потом повязка бантиков.

9. Любая живая кошка страшнее бумажного тигра: плохая работающая программа лучше неработающей хорошей.

10. Свою оценку времени разработки умножай на два.

11. Самый дорогой ресурс разработки – время.

12. Программисту платят за работающую программу, а не за красоту её написания.

13. Любая работающая программа предварительно проходит три стадии: сначала совсем не работает, потом работает, но не так, наконец, работает чуть-чуть не так. Самая плохая третья стадия.

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

15. Отладка на “краях” относится к отладке в “середине” как 5 : 1.

16. Вам никогда не найти в программе последней ошибки.

17. Если тебе кажется, что ты нашёл последнюю ошибку в программе – опиши программу.

18. Если ты долго не можешь локализовать ошибку – значит, ищешь её не там.

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

20. Не так страшна отладка программы, как её сопровождение.

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

^

Список литературы

1. Аммераль Л. STL для программистов на C++; М. ДМК; 1999 – 240стр
   
2. А. Я. Архангельский Программирование в C++Builder 5, М, Бином, 2000;
   
3. Брукс Ф. Мифический человеко-месяц или как создаются программные системы;
   Санкт-Петербург: Символ-Плюс; 2000 – 298стр
   
4. Буч Г. Объектно-ориентированный анализ и проектирование; Санкт-Петербург; Бином;
   2001 – 560стр
   
5. Гласс Р. Руководство по надёжному программированию; М. Финансы и статистика;
   1982 – 256стр
   
6. Майерс Г. Надёжность программного обеспечения; М. Мир; 1980 – 360стр
   
7. Мартин Дж. Планирование развития автоматизированных систем; М. Финансы и статистика; 1984 – 196стр
   
8. Срауструп Б. Язык программирования C++; М. Бином; 1999 – 990стр
   
9. Форсайт Дж. и др. Машинные методы математических вычислений; М. Мир; 1980 – 280стр
   
10. Шилдт Г Самоучитель С++; Санкт-Петербург; BHV, 1997 – 510стр
    

Содержание