Диссертация (1149623), страница 3
Текст из файла (страница 3)
Наконец, описываются подходы, технологии и модели,используемые в диссертационной работе: редакционное расстояние, интервальные деревья, технологии DocBook и DocLine, средства Clone Miner и Pandoc. Наосновании обзора делаются выводы и обосновываются методы исследований,применённые в диссертации.1.1. Документация программного обеспеченияДокументация программного обеспечения является очень важным аспектомразработки компьютерных систем и одновременно одним из самых дискуссионных. Ещё в 1970 году одним из первых о важности документации ПО писалВ.
Ройс (W. Royce) [127] в своей знаменитой статье, посвящённую водопадноймодели. Он считал, что для того, чтобы разработать программное обеспечениена сумму 5 миллионов долларов, должно быть написано не менее 1000 страницдокументации (при этом он имел в виду проектную, а не пользовательскую, документацию). С тех пор дискуссия вокруг необходимого количества документации не прекращается. Ф. Брукс (F.
Brooks) в своей знаменитой книге «Мифический человекомесяц» [2] отмечает, что на начало 70-х годов программисты так ине научились создавать хорошую документацию. Проблемы в отечественныхпрограммных проектах, связанные с документацией, отмечались многими исследователями в 90-х и 2000-х годах, например, А.Н. Тереховым [25], А.А. Шалыто [27], В.В. Липаевым [15]. В 2001 году был опубликован Agile-манифест11(авторы — К. Бек (K. Beck), А. Кокбурн (A. Cockburn), М. Фаулер (M. Fowler) идругие известные специалисты в сфере разработки ПО) [28]. Один из принциповманифеста гласил, что работающий продукт важнее исчерпывающей документации. В том же 2001 году в [141] указывалось, что никто не знает, какие видыдокументации необходимы и полезны для разработчиков и помогают понимаюсистемы, а также кто и когда должен её создавать.
В 2003 году неоднозначноеотношение к документации ПО отмечают Т. Лезбридж (T. Lethbridge) с коллегами [95], делая выводы на основании опроса разработчиков в различных компаниях. Наконец, в 2011 году Д. Парнас отмечает, что ситуация с документацией впрограммных проектах по-прежнему остаётся нерешённой [114].Не вдаваясь глубоко в детали данной дискуссии следует отметить, что ситуация с документацией для открытых проектов (open source projects) на настоящиймомент очевидно неблагополучна. Одним из самых ярких примеров являетсяпроект Linux Kernel; проблемы с его документацией активно обсуждаются сообществом [51, 108]. Также многие исследователи и практики отмечают проблемыв данном вопросе для различных видов проектов. Наконец, опыт автора по участию в различных проектах — сопровождение систем в режиме аутсорсинга, созданных сторонними командами, создание требований по доработке существующих систем, реинжиниринг систем, функционирующих на устаревших платформах, и т.д.
— явно свидетельствует о наличии проблем с документацией. Приэтом участники проектов в целом, как правило, имеют необходимую профессиональную подготовку благодаря тому, что обучению в области программирования уделяется должное внимание при разработке и реализации современных образовательных стандартов [5, 24], но применение полученных в академическойсреде знаний на практике бывает затруднительным и не всегда оказываетсяуспешным. Таким образом, необходимы дополнительные исследования, а такжесоздание новых методов и подходов в области работы с документацией ПО.Рассмотрим различные виды документации ПО согласно различным классификациям, имеющимся в литературе.
Известный методолог программной инженерии И. Соммервил (I. Sommerville) выделил следующие виды документации:12документацию процесса и документацию продукта [133]. В первый вид документации он включил различные описания процесса разработки ПО — планы проекта, отчёты, используемые в проекте стандарты. Остановимся подробнее навтором виде документации — документации продукта, — который, следуяИ. Соммервилу, состоит из пользовательской документации (user documentation)и документации системы (system documentation).Пользовательская документация включает в себя описание предоставляемыхсистемой сервисов, а также руководство по её установке, руководство по началуработы (getting started with the system), руководство пользователя (то есть описание функциональных возможностей системы — user manual, user reference), руководство по администрированию (system administration guide).Документация системы включает в себя спецификацию требований, спецификацию архитектуры, описание функциональности и интерфейсов компонент, листинги кода (возможно, включая комментарии), документы по тестированию(validation documents) и руководство по сопровождению (maintenance guide).Известный специалист по разработке документации Т.
Баркер (T. Barker) [38]разделяет документацию ПО на разработческую и пользовательскую. Первыйвид включает в себя внешнюю документацию, ориентированную на пользователей и заказчика, и внутреннюю документацию, описывающую статус проекта,включающую отчёты об изменениях, а также тесты, ревью и пр.
Перечислимвиды внутренней документации, отмечаемые Т. Баркером: спецификация проекта (project specification); план проекта (project management plan); документация кода (internal code documentation); отчёты по тестированию (test/usability reports).Т. Лезбридж с коллегами, делая обзор ситуации с документацией ПО на основе опроса разработчиков, выделяют следующие виды документации [95]: спецификация требований (requirements); спецификация системы (specifications);13 архитектура (architectural documents); детальная архитектура (detailed design); низкоуровневая архитектура (low level design); документация по тестированию (testing/quality documents).Интересный взгляд на документацию ПО предлагает Д. Парнас [114]: он разделяет документацию на описательную (narrative) и справочную (reference).
Описательная документация предназначена для прочтения целиком, её читателиобычно мало знакомы с предметом и нуждаются во вводной информации и общих сведениях. Написание такой документации является, по мнению Д. Парнаса,искусством. Справочная документация предназначена для выборочного чтения,и, как правило, читатель хорошо знаком с предметной областью и не нуждаетсяво вводной информации. В случае с этой документацией возможны технологи иинженерные подходы. Продолжая идею Д. Парнаса, следует отметить, что справочная документация, как правило, описывает наборы однотипных сущностей —элементы пользовательского интерфейса (руководства пользователей), типы иструктуры данных, функции, прерывания (API документация и руководства программистов), конструкции языков программирования (руководства по языкампрограммирования).
Реже такая документация описывает процессы, например,процесс использования драйвера: его инициализация, запуск и т.д. Следует отметить, что на практике реальная документация часто бывает смешанной, то естьможет содержать описательную и справочные компоненты, при это строгость иформальность описания справочных компонент документации может быть различной.Многие исследователи выделяют так называемую API-документацию[57, 76, 110, 111, 112, 128, 139]. Она описывает программные интерфейсы библиотек и модулей: функции, классы, типы данных и константы, и т.д. API-документация является справочной, и, как правило, её структура отражает структуру14документируемого программного обеспечения. Часто эта документация автоматически генерируется по программному коду системы такими инструментамикак Javadoc [84], консолидируя комментарии в коде.Принимая во внимание приведённые выше классификации, автор диссертационного исследования выделил следующие виды документации ПО, делая акцентна доступности соответствующих документов (последнее необходимо, поскольку в исследовании требовались для анализа документы реальных проектов). Спецификация требований — присутствует во всех классификациях; авториспользовал данный вид документации из коммерческих проектов, в которых он принимал участие. Спецификация архитектуры — у И.
Соммервилла и Т. Лезбриджа этот виддокументации упомянут явно, у Т. Баркера информация об архитектуре системы может присутствовать в спецификации проекта и документациикода. Руководство пользователя — присутствует у И. Соммервилла и Т. Баркера,отсутствует у Т. Лезбриджа; последнее объясняется тем, что Лезбридж рассматривал документацию разработчиков. В целом пользовательская документация традиционно стоит особняком от документации иного вида —имеются специальные методы по её разработке [62, 94, 77, 148], и, как правило, её создают не программисты, а специальные технические писатели.Следует отметить, что данная документация легко доступна в целях исследований — как для коммерческих проектов (она обычно не составляет, вотличие от иных видов документации, коммерческой тайны), так и для открытых проектов.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
