ДОКУМЕНТИРОВАНИЕ ИСХОДНОГО КОДА

​

​

ОБЩИЕ ТРЕБОВАНИЯ

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

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

ОБЩИЕ ТРЕБОВАНИЯ

​

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

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

​

ОБЩИЕ ТРЕБОВАНИЯ

o Имейте в виду, что комментарии в заголовочных h-файлах предназначены для пользователей классов, тогда как комментарии в CPP/CS-файлах реализации предназначены для разработчиков этих классов.

ОБЩИЕ ТРЕБОВАНИЯ

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

ОБЩИЕ ТРЕБОВАНИЯ

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

​

ИСХОДНЫЕ ФАЙЛЫ

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

�

ИСХОДНЫЕ ФАЙЛЫ

o Каждый .cpp-файл должен включать в себя соответствующие заголовочные файлы (.h-files), которые должны содержать:

• объявление типов и функций, которые используются функциями или методами класса, реализуемого в данном .cpp-файле;
• объявление типов, переменных и методов классов, которые реализуются в данном .cpp-файле.�

СТРУКТУРА ИСХОДНОГО ФАЙЛА

o Каждый исходный файл в проекте должен иметь определенную структуру.

o Если некоторый раздел не содержит информации, его можно опустить, но порядок разделов менять не разрешается.��

СТРУКТУРА ИСХОДНОГО ФАЙЛА

o Наличие комментария, обозначающего начало нового раздела и содержащего имя этого раздела, не обязательно, но весьма желательно. Дело в том, что имеется целый ряд утилит для автоматической генерации документации по откомментированному в соответствии с формальными правилами тексту программы (например, Cweb). Такие утилиты очень помогают, в особенности, тем, кто, не являясь разработчиком, должен модифицировать программу.��

СТРУКТУРА ИСХОДНОГО ФАЙЛА

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

​

ДОКУМЕНТИРОВАНИЕ КАТАЛОГОВ

o Каждый каталог должен содержать README файл, в котором описано:

• Назначение каталога и его содержимое.
• Одна строка комментария на каждый файл. Комментарий обычно извлекается из поля NAME оглавления файла.

​

ДОКУМЕНТИРОВАНИЕ КАТАЛОГОВ

o Описание процедуры инсталляции.

o Перечень ресурсов и ссылки на них:

o каталоги исходных файлов;

o оперативная документация (справочная система и др. доступные в электронной форме руководства);

o перечень бумажных документов (т.е. документов, представленных не в электронной форме). �

ТРЕБОВАНИЯ К КОММЕНТАРИЯМ

o Комментарии должны формулироваться таким образом, чтобы, если их извлечь из кода программы, они составили осмысленное связное изложение – описание функционирования программы.�o Комментарии должны документировать принимаемые вами решения (что вы делаете в данном месте программы и почему). �

ТРЕБОВАНИЯ К КОММЕНТАРИЯМ

o Комментарии должны быть лаконичными и понятными. Встроенные ключевые слова (gotchas) можно использовать, чтобы отметить места, чреватые проблемами.

o Gotcha Keywords – ключевые слова в комментарии.

:TODO: topic. Означает: ЗДЕСЬ НАДО ДОРАБОТАТЬ. НЕ ЗАБУДЬ.

:BUG: [bugid] topic. Означает: ЗДЕСЬ НАХОДИТСЯ ИЗВЕСТНЫЙ BUG. Объясните его причину и присвойте ему идентификатор (bug ID) �

o :KLUDGE: Если вы сделали что-то неудачное, объясните, как это произошло, и что вы намерены делать впредь, чтобы избежать этого в будущем.

o :TRICKY: Предупреждение, что следующая часть программы очень сложная, ее не следует изменять без тщательного обдумывания.

o :WARNING: Предупреждение о чем-либо.

�

o :COMPILER: Иногда требуется решить проблему с компилятором.�Задокументируйте ее. Проблема может быть решена позднее.

�o :ATTRIBUTE: value. Общий вид атрибута, вставленного в комментарий. Вы можете задавать собственные атрибуты, ком могут быть извлечены из комментария. �

ОПЕРАТОРЫ . ОПЕРАТОР IF…ELSE

Если if завершается оператором return, то не используйте else.

Код получается более понятным.�Так, вместо

if (condition) return 0;�else�{�do_something();�}

лучше написать

if (condition) return 0;�do_something(); �

ОПЕРАТОР IF…ELSE

В этом случае последним return может быть выдача кода ошибки (это позволит отловить «случайное» попадание в ненужную ветвь алгоритма).

�o Необходимо стараться проверять все альтернативные возможности (в том числе все “предельные случаи”) �

ЦИКЛЫ

• По возможности следует избегать циклов do…while. Они опасны тем, что тело цикла исполняется всегда хотя бы один раз. Кроме того, при чтении программы очень трудно отыскать проверяемое условие, т.к. while в такой конструкции располагается «внизу», т.е. в конце тела цикла. По этим причинам никогда не следует употреблять do…while для организации бесконечного цикла – для этой цели намного лучше использовать while(1). �

ЦИКЛЫ

• Всегда используйте оператор for, если присутствуют любые два из инициализирующего, условного или инкрементного выражений. Это сокращает код и делает его более понятным. �

КОНСТАНТЫ И ПЕРЕЧИСЛЕНИЯ

Следует помнить, что const int на самом деле не задает константу, а резервирует память под int (хотя и запрещает менять содержащееся в ней значение). Под перечисление enum память никогда не выделяется, поэтому использование enum может быть предпочтительнее.

�

МОБИЛЬНОСТЬ

Мобильность программ – это свойство, позволяющее выполнять программы на разных компьютерах, под управлением разных операционных систем, с минимальными изменениями кода. Естественно, мобильность предусматривает и возможность трансляции программы разными компиляторами. Думать о мобильности нужно даже в том случае, если предполагается, что программа пишется, скажем, только «под» Windows и только с использованием MS Visual C++ (т.е. никогда не планируется использовать другой компилятор).

�

МОБИЛЬНОСТЬ. ЗАВИСИМОСТЬ ОТ КОМПИЛЯТОРА

Некоторые детали в C/C++ не стандартизованы. Например

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

o некоторые директивы и ключевые слова (в основном это директивы препроцессора) поддерживаются только определенными компиляторами.

�

ЗАВИСИМОСТЬ ОТ КОМПЬЮТЕРА

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

o Размеры данных базовых типов (int, float, double, char и т.п.) в байтах и в машинных словах могут быть разными у разных компьютеров и в разных операционных системах. Гарантировано только, что размер short не меньше размера int, размер float не меньше размера double и т.п.

�

ЗАВИСИМОСТЬ ОТ КОМПЬЮТЕРА

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

o Символы (char) могут иметь знак. Для повышения мобильности можно использовать явное описание unsigned char или преобразовывать символы перед обработкой к типу unsigned char.

��