Уровень модуля

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

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

'Имя файла:

' Автор:

'Дата:

'Описание:

'Зависимости:

'Обновления:

Готовый комментарий выглядит примерно так:

'Имя файла: NETAPIs.cls

'Автор: Стив Браун

'Дата: 6 июня 1998 г.

'Описание: Библиотека содержит объявления и константы

'сетевых функций Win32 API. Оболочки, оформленные в виде открытых 'свойств и методов, избавляют программистов от необходимости 'осуществлять преобразование символов из кодировки ANSI в Unicode.

'Зависимости: Нет

'Обновления: 6-6-98

'Дата создания библиотеки.

Добавлены процедуры для работы с контроллером домена, а также функции для глобальных пользователей и групп. 8-14-98 Добавлены функции проверки локальных пользователей.

ПОДСКАЗКА Если ваш код предназначен для многократного использования, включите в секцию модуля (General)(Declarations) комментарий с описанием процедур модуля, а также требований или зависимостей данного модуля. В этом случае другим программистам будет проще узнать, какие условия необходимы для работы вашей программы.

Уровень процедуры

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

'

'Процедура: AddUser()

'Автор: Стив Браун

^'Дата: 6 января 1998 г.

'Описание: Функция добавляет глобального пользователя в домен

'Требования: Для работы данной функции необходимо

предварительно

задать значения свойств UserID и Password.

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