Записки программиста Программирование и не только

Венгерская нотация (Hungarian Notation)

Автор: Charles Simonyi (Чарльз Симонии), Корпорация Microsoft, ноябрь 1999
Перевод: Nick E. Geht (Гехт Николай), Центр Интернет ОмГУ, декабрь 1999

Резюме документа

"Венгерское соглашение" об именах идентификаторов Чарльза Симонии.

Примечание от dr. GUI

Еще во времена разработки первых версий DOS, доктор Чарльз Симонии представил соглашение об именах идентификаторов, в котором для указания функционального назначения объекта, представленного идентификатором используется добавление префикса к имени идентификатора.

Данная система является широко используемым внутренним стандартом фирмы Microsoft. Причиной для этого является то, что префиксы к именам делают просмотр исходных текстов и спецификаций более простым. Название "Венгерская нотация" появилось из-за того, что имена переменных как бы написаны на иностранном языке, и сам доктор Симонии родом из Венгрии.

Венгерская нотация является одной из методик, позволяющих программистам создавать более читаемый код в короткие сроки. В большей части документации и файлов заголовков, изданных Microsoft за последние 15 лет используется Венгерская нотация. Многие программисты вне Microsoft приняли данное соглашения или другую сходную схему формирования имен идентификаторов.

Возможно самой важной публикацией, пропагандирующей Венгерскую нотацию была первая книга, читаемая почти каждым Windows - программистом: "Windows programmin" Чарльза Петцольда. В книге данное соглашение использовалось для примеров и примечаний и было кратко описано в первой главе.

Данный документ представляет первоначальный вариант работы Симонии.

Соглашение об идентификаторах в программе.

Данный документ предназначен для изложения основных достоинств о формальном формировании идентификаторов.

При введении нового идентификатора в программу, хороший программист учитывает следующие факторы:

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

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

Преимущества Соглашений

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

Названия будут мнемоническими в строго определенном смысле: идентификатор будет очевиден для того, кто помнит название характеристики или принцип его построения.

Названия имеют смысловое значение: должна быть возможность отобразить любое название в наборе характеристик.

Названия будут непротиворечивы, так как произведены теми же самыми правилами.

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

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

Правила обозначения

Предлагаются следующие правила обозначения:
1) Описание характеристики идентификатора входит в идентификатор. Удобной пунктуацией является указание характеристики перед названием, с разделением их (началом названия с большой буквы в Cи, например: rowFirst: row - характеристика, Fist - название).

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

3) Простые типы названы короткими тегами, которые выбраны программистом. Такие теги должны быть интуитивно понятны большинству программистов.

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

Я рекомендую использование нового тега для каждой новой структуры данных. Тег с некоторой пунктуацией (первая или все заглавные буквы) тоже может и должен использоваться как имя типа для структуры. Использование новых тегов так же оправдано в тех случаях, когда это влияет на удобочитаемость программы.

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

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

Например мы создаем графическую программу. В данном случае у нас существует тип данных "цвет". Естественным желанием является сделать префикс color для обозначения цвета. Однако при детальном рассмотрении может оказаться, что применение термина color более удобно в приложении к названию, например: LineColor. Для обозначения цвета более выгодным является сокращение, например clr. clrDefault.

Обозначение для упрощения написания.

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

Обозначение для процедур.

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

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

2) Начинайте название процедуры с тега типа возвращаемого значения, если таковое существует.

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

4) В конец названия можно добавить список тегов некоторых или всех формальных параметров, если есть смысл.

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

Таблица 1. Некоторые примеры для названий процедуры

Описание	Название
InitSy	Берет sy как его параметр и инициализирует его.
OpenFn	fn - параметр. Процедура "откроет" fn. Никакое значение не будет возвращено.
FcFromBnRn	Возвращает fc, для переданной пары Bn,Rn (Названия не передают нам информации о типе данных для Fc, Rn, Bn).

Далее приведен список стандартных конструкций, X и Y замещают произвольные теги.

Таблица 2. Стандартные конструкции типа

pX	Указатель на X.
dX	Различие между двумя образцами типа X. X + dX имеет тип X.
cX	Индекс образцов типа X.
mpXY	Массив Ys, индексированного по X.
rgX	Массив Xs.
iX	Индекс массива rgX.
grpX	Группа Xs, сохраненных последовательно. Используется когда X элементы имеют переменный размер и не применима стандартная индексация. Элементы X индексируются способом, отличным от обычного.
bX	относительное смещение к типу X. Используется для обращений к полям переменной длины в структурах. Смещение может быть указано в байтах или словах, в зависимости от вида индексации.
cbX	Размер X в байтах.
cwX	Размер X в словах.

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

Далее приведены стандартные имена. X замещает любой тег типа, записанный в нижнем регистре.

Таблица 3. Стандартные спецификаторы

XFirst	первый элемент в упорядоченном наборе X
XLast	последний элемент в упорядоченном наборе X
XLim	строгий верхний предел набора значений X. Границей цикла должно быть X < XLim.
XMax	строгий верхний предел набора значений X. Если X начинается с 0, то XMax равен числу различных значений X.
XT	временное значение X.

Таблица 4. Некоторые базовые типы

f	Флажок (Булева переменная, логическое значение). Используемое название должно относиться к истинному состоянию. Исключение: константы fTrue и fFalse.
w	Машинное слово
ch	Символ, обычно в тексте ASCII.
b	Байт
sz	Указатель на строку терминированную нулем (ASCIZ)

Примечание от Николая Гехта

Ниже приведены префиксы типов данных, наиболее часто используемые на данный момент при разработке для Win32

Таблица 5. Базовые префиксы типов данных Win32

g_	префикс для глобальной переменной
m_	префикс для переменной класса
c	константа (префикс для типа)	const
l	длинный (префикс для типа)	far, long
p	указатель (префикс для типа)	*
ch	char	char
b	байт	BYTE, unsinged char
w	16-битное слово (2 байта)	WORD, unsigned short
dw	32-битное слово (4 байта)	DWORD, unsigned long
n,i	целое	int
flt	с плавающей точкой	float
dbl	с плавающей точкой	double
f	логическое	BOOL
sz	ASCIZ строка	char[]
psz	ASCIZ строка	char *
pcsz	константа ASCIZ строка	const char *
pv	произвольный указатель	void *
ppv	указатель на произвольный указатель	void **
h	хендл	HANDLE, void *
unk	OLE объект	IUnknown
punk	указатель на OLE объект	IUnknown *
disp	Automation объект	IDispatch
pdisp	указатель на Automation объект	IDispatch *

Примечание от Axis :)

Специально утащил к себе, чтобы были под рукой правила чтения исходников MicroSoft'а. Теперь хоть отдаленно понятно, что это у них за дикие сокращения.

Скопировано отсюда: http://www.codenet.ru/progr/visualc/Hungarian-Notation.php