Соглашения VBScript
Что такое соглашения?
Соглашения — это советы, которые помогут вам писать сценарии, используя Microsoft Visual Basic Scripting Edition.
Соглашения могут включать следующее:
- Соглашения по именованию объектов, переменных и подпрограмм
- Соглашения по созданию комментариев
- Форматирование текста и документирование
Основной смысл использования соглашений — это стандартизация структуры и стиля
сценария или набора сценариев таким образом, чтобы вы и другие программисты
могли легко читать и понимать ваш код. Использование хорошего стиля программирования
позволяет создавать правильный, читабельный и недвусмысленный исходный код,
который совместим с соглашениями других языков и является интуитивно понятным.
Соглашения по именованию констант
Ранние версии VBScript не имели механизмов для создания пользовательских констант.
Если вы используете константы, то для того, чтобы отличать их от переменных,
рекомендуется при именовании констант использовать верхний регистр. Если имя
константы состоит из нескольких слов, то слова разделяются символом подчёркивания (_). Пример:
USER_LIST_MAX
NEW_LINE
Это рекомендуемый способ именования констант. Однако вы можете использовать
альтернативную схему именования констант. Поскольку объявление констант выполняется
с помощью оператора
Const, то вы можете именовать константы
символами в смешанном регистре с префиксом
con. Например:
conYourOwnConstant
Соглашения по именованию переменных
С целью повышения читабельности и совместимости кода, используйте для именования
переменных префиксы, приведённые ниже в таблице.
| Подтип |
Префикс |
Пример |
| Boolean |
bln |
blnFound |
| Byte |
byt |
bytRasterData |
| Date (Time) |
dtm |
dtmStart |
| Double |
dbl |
dblTolerance |
| Error |
err |
errOrderNum |
| Integer |
int |
intQuantity |
| Long |
lng |
lngDistance |
| Object |
obj |
objCurrent |
| Single |
sng |
sngAverage |
| String |
str |
strFirstName |
Область видимости
По возможности переменные должны объявляться как локальные, то есть область
видимости переменной должна быть как можно меньше. Переменные в VBScrip имею следующие области видимости:
| Область видимости |
Где объявлена переменная |
Видимость |
| Уровень процедуры |
Событие, функция или процедура |
Видима в процедуре, в которой объявлена |
| Уровень сценария |
Раздел HEAD в HTML-странице, вне процедуры |
Видима как в процедурах, так и в сценарии |
Префиксы переменных
Если сценарий очень большой, то для того, чтобы отличать глобальные переменные
от локальных, рекомендуется использовать префиксы. Префикс из одной буквы
применяется для глобальных переменных. Локальные переменные именуются без префикса.
| Область видимости |
Префикс |
Пример |
| Уровень процедуры |
Нет |
dblVelocity |
| Уровень сценария |
s |
sblnCalcInProgress |
Описание имён переменных и процедур
Имя переменной или процедуры должно быть содержательным, то есть соответствовать
назначению этой переменной или процедуры. Имя может состоять из префикса и
символов смешанного регистра. Кроме того имя процедуры должно начинаться с глагола,
например InitNameArray или CloseDialog.
Для часто используемых или длинных терминов рекомендуется применять стандартные
аббревиатуры. В общем случае имена переменных размером более 32 символов слишком
трудны для восприятия. Если используете аббревиатуры, убедитесь, что они содержатся
во всём коде сценария. Например, случайный переход от Cnt к Count может привести
к неприятным неожиданностям (это уже рассматривалось в разделе «2.3.2. Переменные VBScript»).
Соглашения по именованию объектов
В приведённой ниже таблице приведён список рекомендуемых соглашений для объектов,
с которыми вы можете встретиться при программировании в VBScript.
| Тип объекта |
Префикс |
Пример |
| 3D Panel |
pnl |
pnlGroup |
| Animated button |
ani |
aniMailBox |
| Check box |
chk |
chkReadOnly |
| Combo box, drop-down list box |
cbo |
cboEnglish |
| Command button |
cmd |
cmdExit |
| Common dialog |
dlg |
dlgFileOpen |
| Frame |
fra |
fraLanguage |
| Horizontal scroll bar |
hsb |
hsbVolume |
| Image |
img |
imgIcon |
| Label |
lbl |
lblHelpMessage |
| Line |
lin |
linVertical |
| List Box |
lst |
lstPolicyCodes |
| Spin |
spn |
spnPages |
| Text box |
txt |
txtLastName |
| Vertical scroll bar |
bar |
vsbRate |
| Slider |
sld |
sldScale |
Соглашения о комментариях
Все процедуры должны начинаться с короткого комментария, описывающего назначение
процедуры. Этот комментарий не должен описывать алгоритм выполнения процедуры
(то есть как процедура работает), потому что процедура может быть со временем
изменена и такой подробный комментарий может ввести в заблуждение или, в худшем
случае, содержать неверную информацию. Код внутри процедуры снабжается комментариями
каждой строки, описывающий выполнение процедуры.
Параметры процедуры должны быть описаны, если их назначение не очевидно.
Возвращаемые значения для функции и переменные, значения которых изменяется в
процедуре через ссылки на параметры, должны также быть описаны в начале процедуры.
Комментарии, используемые в качестве заголовка процедуры, должны использовать
следующие разделы (для примера см. следующий раздел «Форматирование кода»):
| Раздел заголовка |
Содержание комментария |
| Назначение |
Что делает процедура (но НЕ как делает). |
| Внешние элементы |
Список внешних переменных, элементов управления или других элементов, состояние которых изменяется в процедуре. |
| Действия |
Список действий процедуры над каждой внешней переменной, элементом управления или другим элементом. |
| Входные параметры |
Пояснения для каждого аргумента, назначение которого не является очевидным. Каждый аргумент должен быть описан в отдельной строке. |
| Возвращаемые значения |
Пояснения для возвращаемого значения. |
Помните следующие моменты:
- Каждая важная объявленная переменная должна быть описана в отдельной строке комментария.
- Переменные, элементы управления и процедуры должны иметь осмысленные имена, чтобы в комментариях приводились только описания для сложных случаев и в тех ситуациях, когда требуются подробности.
- В начале вашего сценария вы должны привести общее описание сценария, количество объектов, процедур, алгоритмов, диалоговых окон и других элементов. Иногда полезно описание алгоритмов с помощью псевдокода.
Форматирование кода
Экранное пространство должно использоваться экономно насколько это возможно.
В то же время при написании исходного текста должна посматриваться логическая
структура и вложенность операторов. При этом следует учитывать следующие моменты:
- Стандартные вложенные блоки должны иметь отступы в размере 4 пробелов.
- Общие комментарии процедуры должны быть отделены от кода процедуры одной пустой строкой.
- Высший уровень операторов в теле процедуры должен иметь отступ в 4 пробела, каждый последующий вложенный блок операторов отделяется прибавлением ещё 4 пробелов.
Ниже приведён пример исходного кода, где выполнены указанные здесь рекомендации.
В заключение следует отметить, что это лишь РЕКОМЕНДАЦИИ, а не обязательные условия.
Вы можете разработать свои принципы форматирования кода. Однако, если вы мечтаете работать
в Microsoft (чем чёрт не шутит))), то вам лучше сразу привыкать писать программы по правилам, принятым в Microsoft.
'**************************************************************
' Назначение: Поиск первого вхождения указанного пользователя
' в массиве strUserList.
' Входные
' параметры: strUserList(): список пользователей для поиска.
' strTargetUser: имя искомого пользователя.
' Возврат: Индекс первого найденного элемента массива strUserList,
' в котором выполнялся поиск строки strTargetUser.
' Если указанный пользователь не найден,
' то возвращает -1.
'**************************************************************
Function intFindUser (strUserList(), strTargetUser)
Dim i ' Счётчик
Dim blnFound ' Флаг завершения поиска
intFindUser = -1
i = 0 ' Инициализация счётчика
Do While i <= Ubound(strUserList) and Not blnFound
If strUserList(i) = strTargetUser Then
blnFound = True ' Установить флаг в True
intFindUser = i ' Вернуть количество циклов
End If
i = i + 1 ' Увеличить счётчик на 1
Loop
End Function
