Соглашение об идентификаторах в программе.
Данный документ предназначен для изложения основных достоинств о формальном формировании идентификаторов.
При введении нового идентификатора в программу, хороший программист учитывает следующие факторы:
1. мнемоническое значение: идентификатор должен легко запоминаться
2. смысловое значение: роль идентификатора должна быть ясна из его названия
3. преемственность: часто рассматривается как чисто эстетическая идея, но все же, похожие объекты должны иметь похожие идентификаторы.
4. скорость решения: придумывание, ввод и редактирование идентификатора не должны занимать слишком много времени, идентификатор не должен быть слишком длинным.
Выбор имен может стать задачей, поглощающей лишнее время у разработчика. Часто идентификатор, удовлетворяющий одним условиям противоречит другим. Кроме того, поддержать преемственность имен иногда бывает достаточно трудно.
Преимущества Соглашений
Данные соглашения об идентификаторах обеспечивают удобную технологию для формирования имен, удовлетворяющих вышеупомянутым критериям. Основной идеей является передача основных характеристик идентификатора как части в его названии. Эта простая идея, безусловно, требует уточнения (что, например, предполагается под "критерием", что делать если они(критерии) не уникальны?). Однако, давайте сначала оговорим общие положения.
Названия будут мнемоническими в строго определенном смысле: идентификатор будет очевиден для того, кто помнит название характеристики или принцип его построения.
Названия имеют смысловое значение: должна быть возможность отобразить любое название в наборе характеристик.
Названия будут непротиворечивы, так как произведены теми же самыми правилами.
Построение названий будет производится механически, следовательно быстро.
Выражения в программе могут быть проверены на преемственность методами, похожими на обычные измерения свойств объекта.
Правила обозначения
Предлагаются следующие правила обозначения:
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)
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 *
(
Сообщение от zulkis
