Диссертация (1149623), страница 4
Текст из файла (страница 4)
Отметим особый вид пользовательской документации –руководства по применению систем и отдельных утилит для Unix/Linuxпользователей. Такие пользователи обычно работают в интерфейсе командной строки, являясь, фактически, программистами, поэтому соответствующая пользовательская документация сильно похожа на руководство для15программистов.
Тем не менее, автор диссертационной работы включил такие документы в группу «Руководство пользователя». Руководство программиста — вид документации, который присутствует уИ. Соммервилла как руководство по сопровождению, у Т. Баркера частично как документация кода, частично как руководство по сопровождению (внешняя документация); у Т. Лезбриджа этот вид документации может быть скомбинирован из видов описания архитектуры (однако в явномвиде отсутствует). Данный вид документации важен для данного исследования, поскольку имеется большое количество открытых проектов, документация которых также открыта и доступна для анализа в рамках различных исследований.
При этом в данных проектах при составлении документации особенный упор делается на описание уже созданного кода с цельюоблегчить открытую (open source) разработку. Руководство по администрированию — данный вид документации присутствует у И. Соммервилла и у Т. Баркером в пользовательской документации и отсутствует у Т. Лезбриджа. Этот вид документации был включён вклассификацию в виду доступности таких документов у открытых продуктов. API-документация — отсутствует в явном виде у И. Соммервилла, Т. Баркера и Т. Лезбриджа; может быть отнесена к документации программногокода или к описанию низкоуровневой архитектуре, так как описывает детали кода (классы, атрибуты, функции и т.д.); также может быть отнесена кпользовательской документации, т.к.
предназначена для расширения функциональности системы теми, кто использует сиcтему. API-документациявключена автором диссертационной работы в классификацию в виду широкого распространения в открытых и коммерческих продуктах, а также активных исследований проблем и методов разработки и сопровождения такой документации.16 Справочник по языку — у И. Соммервилла присутствует в документациипроцесса, отсутствует у Т. Баркера и Т. Лезбриджа. Для данного исследования справочники по языку интересны в виду доступности, а также ввидуширокого распространения предметно-ориентированных языков (DomainSpecific Languages, DSLs) [58, 125] и соответствующих средств разработкии использования — следовательно, и соответствующих документов оказывается много.1.2. О повторах в документации программного обеспеченияПри разработке документации широко используется техника copy/paste.
Функциональность ПО содержит значительные повторы, поэтому при составлении документов, при описании очередной сущности (класса, функции, атрибута и т.д.)часто копируется уже существующее описание, которое исправляется и дополняется в соответствии с новым контекстом. Часто таких копирований происходит много, они по-разному редактируются, и в результате в документации накапливается значительное количество повторов, которые оказываются неточными,являясь различными вариациями одной и той же информации. Кроме того,весьма часто раскопируются отдельные фрагменты текста, которые не связанныс общей функциональностью ПО — одинаковые приглашения к рассмотрениюпримеров, похожие замечания, предупреждения, общие вводные фразы в началеразличных разделов и т.д.Разные исследователи по-разному относятся к повторам в документации.
В работах [89, 121] повторы рассматриваются как признак избыточности, и авторывидят в них причину снижения качества документации. Хотя в [89] указываетсяо том, что с одной стороны, повторы затрудняют сопровождение и чтение, но сдругой стороны требуются дополнительные исследования влияния избыточности документации на скорость восприятия, так как, возможно, что во многих случаях эта избыточность наоборот, повышает понятность текста.
В [11, 20, 76,110, 111, 112] повторы в документации связываются с повторами в коде ПО и17активно обсуждается вопрос о повторном использовании документации аналогично повторному использованию кода. В [150] повторы в документации ПО используются для анализа качества документации ПО — их наличие считается признаком плохого качества документов. Итак, разное отношение исследователей кповторам в документации в значительной степени обусловлено разным характером документации, которую анализируют авторы перечисленных работ.Таким образом, справочная документация может и должна содержать большоеколичество повторов в целях максимальной унификации, а также из тех соображений, что подобное должно быть описано одинаково, с минимальным использованием синонимов, минимальным наличием «параллельных мест» в тексте.Рассмотрим подробнее работы, посвящённые анализу повторов в документации ПО.М. Омазиз [112] анализирует API-документацию нескольких известных открытых (open source) программных проектов, созданную с применением Javadoc [84].
То есть в этом случае документация генерируется на основе комментариев. Поиск повторов авторы выполняют с помощью средства собственногосредства поиска повторов в API-документации DocReuse [59], построенного использующего в качестве средства поиска программных клонов библиотекуColibri-Java [49].
В работе представлены результаты анализа встроенной документации следующих известных открытых проектов: Apache Commons Collections, Apache Commons IO, Google-GSON, Guava, JUnit, Mockito, SLF4J. Авторыразделяют найденные повторы на две группы: в первую группу входят фрагменты, получившиеся путём copy/paste, во вторую группу входят повторы, появившиеся в документе в том случае, когда описания сходной функциональностьсовпали. Помимо этого, они предлагают классификацию повторов на основетого, как связаны между собой фрагменты программного кода, которым соответствуют текстовые повторы одной группы.
Выделяются следующие виды обусловленных связями в исходном коде повторов в документации: в 60% случаевчасть документации вызываемого метода копируется в документацию вызывающего; в 28% случаев при наследовании часть документации метода наследника18копируется из документации метода предка; в 8% случаев раскопированный исходный код одинаково документирован; наконец, в 3% случаев частично повторяется документация похожих методов.
Их подход не поддерживает работу с неточными повторами, но авторы признают, что такие повторы часто встречаютсяи важны на практике.М. Хори c коллегами [76] предлагают добавить возможности повторного использования в API-документации (Javadoc). Они предлагают инструмент CommentWeaver, позволяющий пользоваться возможностями повторного использования в Javadoc для Java и AspectJ.
Согласно результатам апробации, проведённой с использованием исходных кодов стандартной библиотеки Java, Eclipse иJavaassist, от 4 до 20% документации Javadoc повторяется. Применение CommentWeaver сокращает объём документации приблизительно на 10%. Неточныеповторы в работе также не рассматриваются.М. Носал и Я. Парубан [111] расширяют подход из работы [76] неточными повторами. Они дают следующее определение неточных повторов, называя последние Documentation Phrases: множество фрагментов документа, которые имеютодинаковую семантику или описывают одно и то же свойство, принадлежащеедокументируемым элементам программного обеспечения.
Таким образом, авторы сопоставляют группу повторов определённому свойству программногообеспечения (более точно, исходному коду ПО). Предлагаемый авторами инструмент поддерживает добавление стандартных Documentation Phrases в документацию Javadoc на основании аннотаций1 в исходном коде на Java. Но вопроспоиска Documentation Phrases работа не затрагивает. Определение неточных повторов неформально.Аннотация в Java — это способ указывать дополнительную метаинформацию, относящуюсяк сущностям программы, таким, как классы, методы и т.д. [87].
Аннотации также поддерживаются многими другими современными языками программирования, например, Microsoft C#и Python 3.119Следующая работа М. Носала и Я. Парубана [110] посвящена поиску и анализу повторов в документации в формате Javadoc с использованием модифицированного статического анализатора кода PMD [115]. В работе анализируютсяисходные коды и Javadoc-комментарии 5 проектов с открытым исходным кодом,в том числе Java Framework версии 8.
Результаты анализа показывают большоеколичество найденных повторов в документации, причём фрагменты, повторяющиеся многократно, встречаются реже, чем повторяющиеся небольшое количество раз.Э. Юргенс [89] исследует точные повторов в спецификациях требований, используя для этой цели программный пакет Clone Detective [88]. Ищутся повторыдлиной от 20 слов. Авторы проанализировали 28 документов из различных проектов и классифицировали найденные повторы следующим образом: описаниепошагового взаимодействия пользователя с системой, перекрёстные ссылки,спецификация графических интерфейсов, пояснение к нефункциональному требованию, описание программного интерфейса, пре/постусловие и инвариант впрограмме, описание настроек, функциональное требование, информация о применяемых технологиях, уточнение к требованию.
Помимо самих требований, вработе анализируется их влияние на программный код. Авторами выделяютсятри ситуации: программный код содержит повторное использование, при этом повторы втребованиях не приводят к повторам в коде; например, в требованиях неоднократно упоминается, что при возникновении ошибки информация оней записывается в журнал; соответственно, в коде имеется одна процедуразаписи в журнал, которая многократно вызывается из разных контекстов; дублирование требований соответствует дублированию программногокода; упомянутая выше функциональность о записи в журнал при возникновении ошибки реализована как раскопированный код;20 одинаковая функциональность, описанная при помощи одинаковых требований, реализуется многократно; упомянутая выше функциональность о записи в журнал при возникновении ошибки реализована несколько раз поразному.Процесс поиска повторов в документации выглядел так.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
