Комментарии в программе

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

Уровень приложения

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

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

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

' Имя приложения:

' Версия:

' Copyright:

Товарные знаки:

' Автор/организация:

' Назначение:

' Требования:

После заполнения всех полей комментарий должен выглядеть примерно так:

' Имя приложения: Программа для работы с файлами журналов

Версия: 1.1

'Copyright: 1998-ABCSoftware

'Товарные знаки: Нет

'Автор/организация: Джейн Доу/АВС Software

'Назначение: Приложение читает и анализирует файлы журналов.

'Может использоваться для централизованного управления системными журналами через единый интерфейс с общим набором инструментов

'Требования:

Клиент: Windows 95 / Windows NT 4.0

Сервер: MS SQL Server 6.5

MS Transaction Server 2.0

Файл с комментариями включается в приложение. Если кому-нибудь потребуется проверить приложение, из файла с описанием проекта можно узнать, что необходимо для успешной компиляции и работы приложения. Сначала эти файлы приходилось создавать вручную, но потом я написал специальную надстройку, которая автоматизировала выполнение этой задачи. Эта надстройка рассматривается в уроке 16, «Расширение IDE c помощью надстроек».

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

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

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

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

'Имя файла:

' Автор:

'Дата:

'Описание:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Уровень программы

Существуют комментарии и более низкого уровня — они включаются непосредственно в программу. Обычно они используются в тех случаях, когда некоторая строка кода требует особого внимания. Благодаря своему коллеге Скотту я начал использовать особую форму комментариев, которая упрощает процессы документирования и отладки (особенно в условиях рабочих групп). В следующей таблице приведены некоторые из этих комментариев.

Обозначение	Описание
'	Комментарий общего назначения. Используется для любых пометок, не требующих особого внимания
'???	Спорный фрагмент программу. Особенно полезен при работе в составе группы, а также при отладке чужих программ. Обозначает код, который может оказаться спорным или избыточным, или же потребовать вашего внимания позднее
'!!!	Код требует особого внимания! Комментарий напоминает об этом программисту. Может использоваться для кода, который необходимо тщательно проверить, удалить или восстановить в прежнем виде

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

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

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

'!!!"- СБ Удалить, если построение пройдет успешно.

Чтобы найти весь код, который необходимо удалить перед окончательной компиляцией, достаточно выполнить в проекте поиск строки!!! - СБ.

Хотя описанные приемы приносят несомненную пользу, они, конечно, не исчерпывают всех возможностей комментирования. Используйте ту методику, которая покажется вам наиболее удобной. Тем не менее, обязательно соблюдайте единый стиль комментирования — это сэкономит время отладки приложения!

Соглашения об именах

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

Как вы уже знаете, каждый компонент в проекте Visual Basic должен иметь уникальное имя. Visual Basic автоматически присваивает имена компонентам, включаемым в проект. Например, первой форме проекта по умолчанию присваивается имя Form1. Если оставить свойству Name это значение и включить в проект другую форму, Visual Basic автоматически присвоит ей имя Form2. Следующей форме будет присвоено имя Form3 и т. д. Имена элементов назначаются аналогичным образом. Автоматическое назначение имен может показаться удобным, но представьте себе форму с двенадцатью кнопками, которые носят имена от Command1 до Command12. Конечно, это не помешает нормальной работе программы, но во время написания кода вам будет трудно вспомнить, что делает та или иная кнопка.

ПОДСКАЗКА Первое, что следует сделать при включении нового компонента в проект, — задать его свойству Name какое-нибудь содержательное значение. Ваша программа станет более понятной, а это ускорит процесс разработки и отладки.

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

О Имена переменных могут содержать символы верхнего и нижнего регистра, но без пробелов (например, UserName).

О Имена констант должны содержать символы только верхнего регистра, а вместо пробелов должны использоваться символы подчеркивания (например, ACCESS_ LEVEL_ADMIN).

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

Элемент	Префикс	Пример
Форма	frm	frmMain
Кнопка	cmd	cmdOK, cmdCancel
Надпись	lbl	IblName
Текстовое поле	txt	txtLastName
Комбинированное поле	cbo	cboAccounts
Список	1st	IstGroups
Рамка	fra	fra0ptions
Переключатель	opt	opt0n, opt0ff
Флажок	chk	chkTaxDeductible
Графическое поле	pic	picWaterMark
Рисунок	img	imgSplasGraphic
Полоса прокрутки	scr	scrVolume
Таймер	tmr	tmrCountDown
Список устройств	drv	drvDisk
Список каталогов	dir	dirDirectories
Список файлов	fil	filHiddenFiles
Линия	lin	linSeparator
Фигура	sha	shaCircle
Элемент данных	dat	datLogDatabase
Элемент OLE	pie	oleWordDocument
Дерево	tvw	tvwGroups
Табличный список	lvw	IvwUsers
Список изображений	iml	imlGroups, imlUsers
Строка состояния	sts	stsAccountStatus