Исполнители46. Документирование программного обеспечения: руководство пользователя. Под документацией пользователя понимается документация, которая обеспечивает конечного пользователя информацией по установке и эксплуатации программного пакета. Под информацией на упаковке понимают информацию, воспроизводимую на внешней упаковке программного пакета. Ее целью является предоставление потенциальным покупателям первичных сведений о программном пакете. Пользовательская документация программного средства объясняет пользователям, как они должны действовать, чтобы применить данную программу. Она необходима, если программа предполагает какое-либо взаимодействие с пользователями. К такой документации относятся документы, которыми руководствуется пользователь при установке программы с соответствующей настройкой на среду применения, при применении программы для решения своих задач и при управлении программой (например, когда данное программное средство взаимодействует с другими системами). Эти документы частично затрагивают вопросы сопровождения программного средства, но не касаются вопросов, связанных с модификацией программ. В связи с этим следует различать две категории пользователей: ординарных пользователей программы и администраторов. Ординарный пользователь программы (end-user) использует программу для решения своих задач (в своей предметной области). Это может быть инженер, проектирующий техническое устройство, или кассир, продающий железнодорожные билеты с помощью данной программы. Он может и не знать многих деталей работы компьютера или принципов программирования. Администратор программны (system administrator) управляет использованием программы ординарными пользователями и осуществляет сопровождение программного средства, не связанное с модификацией программ. Например, он может регулировать права доступа к программе между ординарными пользователями, поддерживать связь с поставщиками программы или выполнять определенные действия, чтобы поддерживать программу в рабочем состоянии, если оно включено как часть в другую систему. Состав пользовательской документации зависит от аудиторий пользователей, на которые оно ориентировано, и от режима использования документов. Под аудиторией здесь понимается контингент пользователей, у которого есть необходимость в определенной пользовательской документации. Удачный пользовательский документ существенно зависит от точного определения аудитории, для которой он предназначен. Пользовательская документация должна содержать информацию, необходимую для каждой аудитории. Под режимом использования документа понимается способ, определяющий, каким образом используется этот документ. Обычно пользователю достаточно больших программных систем требуются либо документы для изучения программного средства (использование в виде инструкции), либо для уточнения некоторой информации (использование в виде справочника). Можно считать типичным следующий состав пользовательской документации для достаточно больших программных средств: 1. Общее функциональное описание программного средства. Дает краткую характеристику функциональных возможностей программного средства. Предназначено для пользователей, которые должны решить, насколько необходимо им данное программного средства. 2. Руководство по инсталяции программного средства. Предназначено для системных администраторов. Он должен детально предписывать, как устанавливать системы в конкретной среде. Он должен содержать описание машинно-считываемого носителя, на котором поставляется программное средство, файлы, представляющие программное средство, и требования к минимальной конфигурации аппаратуры. 3. Инструкция по применению программного средства. Предназначена для ординарных пользователей. Содержит необходимую информацию по применению программного средства, организованную в форме удобной для ее изучения. 4. Справочник по применению программного средства. Предназначен для ординарных пользователей. Содержит необходимую информацию по применению программного средства, организованную в форме удобной для избирательного поиска отдельных деталей. 5. Руководство по управлению программным средством. Предназначено для системных администраторов. Оно должно описывать сообщения, генерируемые, когда программные средства взаимодействует с другими системами, и как реагировать на эти сообщения. Кроме того, если программное средство использует системную аппаратуру, этот документ может объяснять, как сопровождать эту аппаратуру. Разработка пользовательской документации начинается сразу после создания внешнего описания. Качество этой документации может существенно определять успех программы. Она должна быть достаточно проста и удобна для пользователя (в противном случае это программное средство, вообще, не стоило создавать). Поэтому, хотя черновые варианты (наброски) пользовательских документов создаются основными разработчиками программного средства, к созданию их окончательных вариантов часто привлекаются профессиональные технические писатели. Кроме того, для обеспечения качества пользовательской документации разработан ряд стандартов, в которых предписывается порядок разработки этой документации, формулируются требования к каждому виду пользовательских документов и определяются их структура и содержание.
47. Документирование программного обеспечения: руководство программиста. Документация по сопровождению программного средства (system documentation) описывает программное средство с точки зрения ее разработки. Эта документация необходима, если программное средство предполагает изучение того, как оно устроена (сконструирована), и модернизацию его программ. Сопровождение - это продолжающаяся разработка. Поэтому в случае необходимости модернизации программного средства к этой работе привлекается специальная команда разработчиков-сопроводителей. Этой команде придется иметь дело с такой же документацией, которая определяла деятельность команды первоначальных (основных) разработчиков программного средства, - с той лишь разницей, что эта документация для команды разработчиков-сопроводителей будет, как правило, чужой (она создавалась другой командой). Команда разработчиков-сопроводителей должна будет изучать эту документацию, чтобы понять строение и процесс разработки модернизируемого программного средства, и внести в эту документацию необходимые изменения, повторяя в значительной степени технологические процессы, с помощью которых создавалось первоначальное программное средство. Документация по сопровождению программного средства можно разбить на две группы: 1. документация, определяющая строение программ и структур данных ПС и технологию их разработки; 2. документацию, помогающую вносить изменения в программное средство. Документация первой группы содержит итоговые документы каждого технологического этапа разработки программного средства. Она включает следующие документы: Внешнее описание программного средства (Requirements document). Описание архитектуры программного средства (description of the system architecture), включая внешнюю спецификацию каждой ее программы. Для каждой программы программного средства - описание ее модульной структуры, включая внешнюю спецификацию каждого включенного в нее модуля. Для каждого модуля - его спецификация и описание его строения (design description). Тексты модулей на выбранном языке программирования (program source code listings). Документы установления достоверности программного средства (validation documents), описывающие, как устанавливалась достоверность каждой программы программного средства и как информация об установлении достоверности связывалась с требованиями к программному средству. Документы установления достоверности включают прежде всего документацию по тестированию (схема тестирования и описание комплекта тестов), но могут включать и результаты других видов проверки программного средства, например, доказательства свойств программ. Документация второй группы содержит Руководство по сопровождению программного средства (system maintenance guide), которое описывает известные проблемы вместе с программным средством, описывает, какие части системы являются аппаратно- и программно-зависимыми, и как развитие программного средства принято в расчет в его строении (конструкции). Общая проблема сопровождения программного средства - обеспечить, чтобы все его представления шли в ногу (оставались согласованными), когда программное средство изменяется. Чтобы этому помочь, связи и зависимости между документами и их частями должны быть зафиксированы в базе данных управления конфигурацией.
48. Стиль кодирования как основа правильной разработки программных средств. Иерархия управляющих конструкций и операторов. Количество операторов в строке. Отступы (сдвиги). Основные правила использования отступов. Шаг сдвигов. Скобки, их разновидности и правила применения. Стиль Кернигана и Ричи. Стиль кодирования. Современные программные продукты суть результат коллективного творчества, поэтому очень важно чтобы все игроки команды разработчиков придерживались единого корпоративного стиля. Корпоративный стиль программирования должен быть зафиксирован специальным документом. Он может быть назван по-разному – CodeBook, Конвенция программирования, Соглашение о стиле написания кода. Смысл его – унифицировать написание кода в команде разработчиков. Соглашение о стиле должно быть очень полным и оговаривать как можно больше аспектов написания кода. Можно сказать, что Соглашение о стиле – это учебник программирования. Основные разделы Соглашения: • Форматирование кода – отступы, пробелы, табуляции. • Имена классов, переменных и функций. • Комментарии, заголовки классов, переменных и функций. • Приемы написания кода – виды циклов и способы их задания, использование указателей. • Логическое построение кода. • Физическое размещение модулей. • Приемы написания кода без ошибок. Соглашение должно постоянно поддерживаться в актуальном состоянии, для этого периодически необходимо собирать дополнения и уточнения и коллегиально обновлять его.
|
