Введение в документирование. Стандарты в документации

Работа добавлена:






Введение в документирование. Стандарты в документации на http://mirrorref.ru

Лекции 8-9

Введение в документирование. Стандарты в документации

План

  1. Вступление.
  2. Стандарты документации
  3. Качество
  4. Метрики
  5. Процесс контроля качества

  1. Вступление.

Разработка программного обеспечения живет документацией. Документация может быть отделена от программного кода, а может быть тесно с ним связана. Для того, чтобы понять важность исчерпывающей документации, представьте, что вам предложили участие в программном проекте, что уже полным ходом идет. По уровню сложности это приблизительно отвечало бы тому, вроде бы вас заставили выучить, например, некоторые аспекты патологии крови. Чтобы сделать это, вам, скорее всего, захотелось бы получить общее представление о предмете, узнать причины необходимости его изучения, потом от обзора постепенно перейти к изучению деталей, диаграмм, которые демонстрируют внутренние связки, описаниям редких случаев и так далее Упущение или противоречия могут привести к частичному, а возможно, и полному непониманию материала, который изучается.

Чтобы проиллюстрировать важность документирования  на разных уровнях, обратимся к фрагменту программного кода (листинг 1.1). Без полной документации этот код невозможно интерпретировать, потому его ценность небольшая, если он вообще хоть что-то стоит. Если мы прибавим комментарии и сделаем имена функций более информативными (листинг 1.2), то получим несколько лучший результат. Этот результат даже может ввести нас в заблуждение, заставив поверить, что мы знаем значение и контекст кода; при этом последствия могут оказаться более катастрофическими, чем в том случае, если бы мы признали непонимание значения текста программы.

Листинг 1.1. Недокументируемый код int а(int i, char з)

{

if(c== "m")

if(i< 1000)

return 0;

else

if(i< 10000)

return 500;

else

return 1200;

else

return 1300; }

Листинг 1.2.Частичнодокументируемыйкод int tax(int anEarning, char aStatus)

{

if(aStatus == "m")

if(anEarning < 1000)

return 0; // Женатые не облагаются налогом, <$1000

else

if(anEarning < 10000)

return 500; //Женат, $1000 - $10000

else

return 1200; // Женат, >=$10000

// Если не женат, то использовать ставку налога в размере $1300

else

return 1300; }

Когда мы смотрим на тщательным образом документируемый программный код (листинг 1.3), его значение становится намного понятнее. Благодаря документированию мы узнаем очень важный новый факт, который заключается в том, что приведенные ставки заработной платы действительны только для ограниченного отрезка времени. Ссылка на одно из требований в SRS является еще одной важной частью документации. Символы, которым предшествует @, относятся к зарезервированным словам Javadoc. Они будут детально рассмотрены в разделе 8.

Листинг 1.3. Документируемый код /**

*Этот метод реализует требование 4.3:

* "Установить действие налога по 01.09.98 по 31.12.99".

* @authorЕ.Брауде

* @version 2.3.4 (08.06.98)

* @param anEarning:зарплата

* @param aStatus: 'm' означает "женатый", другое означает "не женатый"

*/

int tax(int anEarning, char aStatus)

{ . . .

Однако история этой части программного кода еще не закончена. Благодаря управлению конфигурациями из документа План управления конфигурациями ПО мы узнаем, что текущей версией tax() является 2.7.3, а используется версия 2.3.4. Другими словами, фрагмент кода, рассмотренный нами, во многом уже не относится к делу, поскольку текущая версия 2.7.3 может выглядеть совсем по-другому.

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

2.Стандарты документации

В прошлом учреждение стандартов приносило огромные выгоды, которые получаются от новых отраслей инженерии. Стандарт и стандарты документации обеспечивают совместимость между проектами. Это значит, идеи или артефакты, разработанные для одного случая, могут быть перенесены и на другой. Стандарты улучшают понимание среди инженеров. Например, учреждение стандартов в электротехнике привело к большому прорыву вперед в способности проводить широко используемые продукты и услуги. Наиболее крупные компании создали стандарты разработки программного обеспечения. Некоторые заказчики, такие как Министерство обороны США, настаивают, чтобы подрядчики следовали их стандартам.

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

Хемфрі [51] предлагает командам коллективно решать, который из стандартов ведения команда разработчиков; документации им применять. Кажется, такой выбор преимущественно, поскольку команда будет иметь мотив следовать своему собственному решению. Другим преимуществом является то, что компания при этом перебирает разные подходы, а в результате этого процесса, очень вероятно, могут быть приняты наиболее выгодные варианты на длительное время работы. Недостатком самостоятельного выбора стандарта командами является то, что группы, которые работают в одной компании, часто выбирают разные стандарты. Это уменьшает возможности сравнения проектов и требует от инженеров, которые переключаются на другой проект, изучение нового стандарта документации.

Организации должны делать стандарты как минимум простыми и понятными. Организации могут допускать некоторую гибкость и автономность в этом вопросе, но при этом рассчитывать на получение определенной стандартной информации для улучшения всего процесса производства. Например, организация имеет право рассчитывать на получение данных, которые включают время, потраченное на разработку дополнению, и объем программного кода, измеренные указанным способом. Такие стандартные измерения позволяют использовать данные по всей организации. Улучшение процесса включает эволюционный метапроцесс (процесс, который имеет дело с другими процессами) внутри организации. Одним из примеров есть модель зрелости возможностей (CMM) Модель зрелости возможностей (CMM) CMM (Capability Maturity Model), которая классифицирует организации, которые занимаются разработкой программного обеспечения, по пяти категориям растущих возможностей.

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

Институт инженеров по электротехнике и радиоэлектронике (IEEEInstitute of Electrical and Electronic ENGINEERINGIEEE, www. ieee.org) в течение многих лет остается очень активный в создании стандартов документации программного обеспечения. Большинство стандартов разработано разными комитетами, которые состоят из опытных и ответственных инженеров-профессионалов. Некоторыеизстандартов IEEEсталитакжестандартами ANSIANSI (American National Standards Institute).Этот раздел, например, ссылается на три стандарта IEEE.

Международная организация по стандартизации (ISOISO (International Standards Organization) International Standards Organization (ISO)) имеет огромное влияние во всем мире, особенно среди организаций производителей, которые имеют дело с Евросоюзом (ЕС). ЕС приказывает прохождение стандартам ISO любой компании, которая имеет дело со странами — членами Евросоюза, которые являются могучим стимулом для поддержки этих стандартов странами всего мира.

Институт технологий разработки программного обеспечения (SEISEI (Software Engineering Institute) Software Engineering Institute (SEI)) был установлен Министерством обороны США в университете Карнеги-меллон для поднятия уровня технологии программного обеспечения у подрядчиков Министерства обороны. Робота SEI также была принята многими коммерческими компаниями, которые считают улучшение процесса разработки программного обеспечения своим стратегическим корпоративным заданием. В этом разделе приводится важный стандарт, разработанный SEI, который называется Моделью зрелости возможностей (CMM) Модель зрелости возможностей (CMM) CMM (Capability Maturity Model).

Консорциум по технологии манипулирования объектами (OMGOMG (Object Management Group) Object Management Group (OMG), www. omg.org) является некоммерческой организацией, в которую как члены входят около 700 компаний. OMG устанавливает стандарты для распределенных объектно-ориентированных вычислений. В частности, OMG использует унифицированный язык моделирования UML (Unified Modeling Language) Unified Modeling Language (UML) UML как свой стандарт для описания проектов. Например, нотация интерфейса, использованная в описании технологии COMCOM (Microsoft), есть UML -нотацией.

Документы, сопровождающие проект, сильно различаются среди организаций, но приблизительно отвечают фазам водопадов. Стандарт ISO 12207 является одним из примеров такого набора документов.

Рис.1 Документация проекта

Ниже приводится описание каждого документа из набора IEEEInstitute of Electrical and Electronic ENGINEERINGIEEE с ссылками на полные описания в этой книге. Другие стандарты внутренне организованы по тому же принципу.

SVVP (Software Verification and Validation Plan):ПланэкспертизыпрограммногообеспеченияПланэкспертизыПО (SVVP) Software Verification and Validation Plan (SVVP) SVVP (Software Verification and Validation Plan).Этот план определяет, каким образом и в какой последовательности должны проверяться стадии проекта, а также сам продукт на соответствие выставленным требованиям. Верификация — это процесс проверки правильности сборника дополнению; валидация проверяет тот факт, что собран необходимый продукт. Часто валидацию и верификацию осуществляют посторонние организации, в этом случае экспертиза называется независимой (IV&V — Independent V&V).

SQAP (SoftwareQualityAssurancePlan) План контроля качества ПО (SQAP)SoftwareQualityAssurancePlan (SQAP)SQAP (SoftwareQualityAssurancePlan): План контроля качества программного обеспечения.Этот план определяет, каким образом проект должен достичь соответствия установленному уровню качества. Подробные объяснения можно найти в разделе 1.6.5, в примере в конце этого раздела и в разделе 2.

SCMP (Software Configuration Management Plan) План управления конфигурациями ПО (SCMP) SCMP (Software Configuration Management Plan) Software Configuration Management Plan (SCMP): План управления конфигурациями программного обеспечения. SCMP определяет, как и где должны храниться документы, программный код и их версии, а также устанавливает их взаимное соответствие. Было бы очень безрассудным начинать работу без такого плана, поскольку самый первый созданный документ обречен на изменения, а мы должны знать, как управлять этими изменениями до того, как мы начнем складывать документ. В этом разделе приводится описание IEEE SCMP. Для примера мы ограничимся достаточно простым планом, приведенным в конце этого раздела. Средние и большие компании, как правило, стремятся произвести единственное управление конфигурациями для всех своих проектов. Таким образом, инженерам нужно только научиться следовать приказанным процедурам в соответствии с SCMP.

SPMP (Software Project Management Plan): План управления программным проектом План управления программным проектом (SPMP) Software Project Management Plan (SPMP) SPMP (Software Project Management Plan). Этот план определяет, каким образом управлять проектом. Обычно он отвечает известному процессу разработки, например стандартному процессу компании.

SRS (Software Requirements Specification) Спецификация требований к ПО (SRS) Software Requirements Specification (SRS) SRS: Спецификация требований к программному обеспечению. Этот документ определяет требования к дополнению и является подобием контракта и путеводной нити для заказчика и разработчиков.

SDD (Software Design Document) Проектная документация ПО (SDD) SDD (Software Design Document) Software Design Document (SDD): Проектная документация программного обеспечения. SDD представляет архитектуру и детали проектирования дополнению, обычно с использованием диаграмм объектных моделей и потоков данных.

STD (Software Test Documentation) Software Test Documentation (STD)ДокументацияпотестированиюПО (STD) STD (Software Test Documentation): Документация по тестированию программного обеспечения. Этот документ описывает, каким образом должно проводиться тестирования дополнению и его компонентов.

Иногда в проектах притягивается дополнительная документация. Документация для итеративной разработки может быть организована двумя способами. Некоторые документы, в частности SDD, могут содержать свою версию для каждой итерации. Другой способ — дописывать дополнения, которые появляются по мере развития дополнению.

Унифицированная речь моделирования (UML) была разработана для стандартизации описания программных проектов, особенно объектно-ориентированных.UMLбылприняткакстандартконсорциумом OMGOMG (Object Management Group) Object Management Group (OMG).Эта книга использует UML (Unified Modeling Language) Unified Modeling Language (UML) UML как нотация для разных артефактов, включая проектирование и физическую конфигурацию начальных файлов.

Итоговый перечень документации, необходимой для ведения любого проекта, независимо от того, используются ли в нем признанные стандарты документации, такие как IEEEInstitute of Electrical and Electronic ENGINEERINGIEEE, можно определить таким образом (символом «*» отмеченные документы стандарта IEEE, которые могут быть полезные для организации документации).

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

SCMP*

Установите, кто и что будет делать и когда они будут это делать.

SPMP*

Задокументируйте, что должно быть реализовано.

Для себя, для заказчика, для вашей команды;

SRS*

Задокументируйте проектирование дополнению до того, как приступать к программированию.

SDD*

Напишите и задокументируйте программный код.

Задокументируйте тесты, которые проводятся.

Благодаря этому тесты могут быть воссозданы и дополнены.

STD

3.Качество

Есть большая разница тем временем, чтобы просто запрограммировать некоторую функцию и тем, чтобы изготовить ее как качественный продукт. В первом случае мы имеем код, о котором нельзя сказать ничего определенного, кроме того, что он компилируется и, видно, «работает». Во втором случае мы получаем код, который имеет характеристики качественного продукта:

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

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

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

  • расширяемым (готовым к возможным изменениям для расширения функциональности);
  • что развивается (что легко адаптируется к изменению требований);
  • переносимым (пригодным к использованию на нескольких платформах);
  • общим (применимым до нескольких разных ситуаций).

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

4.Метрики

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

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

Метрики, которые необходимо знать практически всегда, включают:

  • объем произведенной работы, измеренный в физических единицах (например, число строк кода);
  • время, потраченное на выполнение работы;
  • степень дефектности (число дефектов на 1000 строк кода, число дефектов на страницу документации и т. д.).

Кроме того, следует применять также относительную оценку качества метрики и качество работы по шкале от 0 до 10.

Предыдущие или желательные значения метрик загодя прогнозируются, а потом сравниваются с полученными результатами. Например, наша организация ожидает 0,2 дефекта на страницу описания требований (в среднем — один на пять страниц, как известно по прошлым проектам). Нашей целью для данного проекта может быть 0,15 дефекту на страницу. Реальная же степень дефектности может складывать 0,17. Это говорит о том, что наши методы лучше использованны в прошлом, однако недостаточно хорошие для достижения поставленной цели.

5.Процесс контроля качества

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

В добавление к ответственности индивидуальных разработчиков и проверкам работы их коллег много организаций определили процесс раздельной систематической и полной проверки, в дальнейшем — контроль качества (QA — quality assurance). В функции контроля контроль качества входят проверки, инспекция (формальный тип проверки, которая приводится ниже) и тестирование. Контроль качества должен начинаться вместе с запуском каждого проекта. Лучше всего привлекать контроль качества и для проверки правильности используемого процесса и актуальности документации. Представитель группы контроля качества часто участвует в инспекции. В идеале контроль качества должен осуществляться некоторой независимой организацией. Много компаний очень малые для осуществления такого сложного контроля качества, и в этом случае сами инженеры осуществляют функции контроля качества по отношению к работе друг друга.

Введение в документирование. Стандарты в документации на http://mirrorref.ru


Похожие рефераты, которые будут Вам интерестны.

1. ТЕХНИЧЕСКОЕ ДОКУМЕНТИРОВАНИЕ

2. ТЕКСТОВОЕ ДОКУМЕНТИРОВАНИЕ

3. Документирование хозяйственных операций

4. ПОНЯТИЕ «ДОКУМЕНТИРОВАНИЕ» И «СПОСОБЫ ДОКУМЕНТИРОВАНИЯ»

5. ДОКУМЕНТИРОВАНИЕ С ПРИМЕНЕНИЕМ ЭЛЕКТРОННО-ВЫЧИСЛИТЕЛЬНОЙ ТЕХНИКИ

6. ДОКУМЕНТИРОВАНИЕ УПРАВЛЕНЧЕСКОЙ ДЕЯТЕЛЬНОСТИ. ТРЕБОВАНИЯ К ДОКУМЕНТАМ

7. Документирование деятельности специалиста филиала ОАО «Ленэнерго» «Кабельная сеть»

8. ОРГАНИЗАЦИЯ И ДОКУМЕНТИРОВАНИЕ РАБОТЫ С ОБРАЩЕНИЯМИ ГРАЖДАН ВИДЫ ОБРАЩЕНИЙ

9. Документирование деятельности и организация работы с документами на примере ЗАО «Общее Дело»

10. Унифицированные системы документации (УСД)

5 stars - based on 250 reviews 5