Соглашение по оформлению документации

Текстовое описание

Текст в любом текстовом редакторе. Сохранение текста производится либо в ТХТ файлы или в формате Ru.OpenOffice.org 2.0 (*.odt). Текст должен быть структурирован: в начале идет заголовок, затем описание или комментарии. При использовании форматированного текста OpenOffice следует применять:

• выравнивание по ширине;

• избегать цветовых выделений текста, использовать лишь при необходимости;

• избегать вставок внешних элементов (например: рисунков JPG/BMP, схем Visio, dbWrench и т.д.) – подобные элементы прилагать в отдельном файле.

Программный код

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

Пример документирования модуля:

/*

=pod

=over 1

=item studinfo.php

=for troff

Скрипт info.php вывод кадровых данных

Автор: Захарова А.С.

Дата: 13.03.2006

Модификации

-----------------------------------------------------------

Автор:

Дата:

Изменения:

TODO:

=back

=cut

*/

function checkuser (in_data)

{

…

…

return $res;

}

Пример частичного документирования:

function checkuser (in_data) // массив in_data с кадровыми данными

{ // (ФИО, возраст, пол)

…

…

return $res; //0 – все обработано, 1 – ошибка обработки

}

Частичное документирование следует использовать по необходимости и на усмотрение разработчика. Документирование модулей следует производить всегда.

Описание структуры базы данных

Для описания структуры базы данных следует использовать инфологическую модель и терминологию: сущность/ связь/ атрибут. В качестве среды описания модели следует использовать dbWrench. Вместе с XML файлами следует делать экспорт в JPG формат для удобства просмотра.

Описание процессов

Для описания бизнес-процессов, принципов работы систем, физической структуры систем следует использовать Visio 2003 (TQM и SDL диаграммы и дополнительные Flowchart объекты (misc flowchart shapes)), а также унифицированный язык моделирования UML.

Архивирование документов

В качестве стандартного архиватора следует использовать ZIP-архиваторы. Все другие архиваторы следует исключить из использования материалов, относящихся к работе над проектами.

Стиль кода

Оформление

1. Использовать 3-4 пробела для отступов;

2. При форматировании текста использовать пробелы;

3. Избегать строк длиннее 78 символов, переносить инструкцию на другую строку при необходимости;

4. При переносе части кода инструкций и описаний на другую строку вторая и последующая строки должны быть отбиты вправо на 3-4 пробела.

5. Оставлять запятую на предыдущей строке так же, как это делается в обычных языках (русском, например);

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

7. Не размещать несколько инструкций на одной строке. Каждая инструкция должна начинаться с новой строки.

Примеры

for (операторы) {…}; // не желательно for (операторы)  //желательно { … };

Пустые строки

Использовать две пустые строки между логическими секциями в коде.

Пробелы в строке

После запятой должен быть пробел. После точки с запятой, если она не последняя в строке (например, в инструкции for), должен быть пробел. Перед запятой или точкой с запятой пробелы не ставятся.

Все операторы должны быть отделены пробелом от операндов с обеих сторон.

2006 © Захарова Анна (диплом)