Kazakh Notation (Казахская нотация)
Автор: Max Skunk (Максим Скунки)
корпорация ОГО-го "Рога и Копыта"
март 2006 года (где-то в степях Казахстана)
Предисловие.
Еще во времена разработки первых версий MS DOS в недрах любимой всеми нами корпорации среди девелоперов появилось соглашение об именах идентификаторов. Суть этого соглашения сводилось к использованию префиксов для указания функционального назначения объектов. Несколько позже данная система была утверждена внутренним стандартом написания кода для всех программеров Майкрософт. Основной причиной этого послужило удобство чтения исходных текстов программ. Вскоре данную систему обработал и окончательно систематизировал доктор Чарльз Симонии (Charles Simonyi). Назвав данное соглашение "Венгерской нотацией". Причиной такого названия послужило то, что сам Симонии родом из Венгрии. В большинстве документов и заголовочных файлов, изданных Майкрософт за последнее время, используются "Венгерская нотация". Но, пожалуй, самую большую популяризацию данной системе положила книга Чарльза Пецольда (Charles Petzold's) Programming Windows.
Сейчас большинство программистов используют данную нотацию или аналогичные системы при оформлении исходного кода своих программ. Исключение из данного правила составляют насильники от один Си. По правде надо сказать, что данная когорта кодеров вообще представляет странное явление, выделяя их в особый легион. По сути, большинство из них как таковыми программистами назвать сложно. Так Барановы Левы (прости меня господи за мое богохульство). Но о них говорить сегодня не будем, посвятив весь материал данной статьи попытки систематизировать оформление кода на великом и могучем языке программирования один Си. За основу мною была взята "Венгерская нотация" доктора Ч.Симонии, если быть еще более точным, то данное является вольным переводом "Венгерской нотации" взятой мной с сайта всеми нами любимой корпорации Майкрософт (http://msdn.microsoft.com/library/techart/hunganotat.htm). Использовать или нет, данное соглашение, решать вам. И так соглашение оформления текстов программ и обозначения идентификаторов на языке один Си или "Казахская нотация".
"Что-то" про идентификаторы, Леву и матушку Германию.
Как сказать по русский, то о чем написал Симонии в своем "Program Identifier Naming Conventions", я точно не знаю. Если говорить по немецкий, то боюсь, вы мало поймете. Там вообще непереводимая игра слов. Поэтому попробуем по албанский.
По утверждениям Чарльза, если вы программер, а не Лева Баранов, то, придумывая новый идентификатор должны подумать за четыре вещи:
- Mnemonic value (мнемоническое значение) – идентификатор должен быть can remember (легко запоминаемым).
- Suggestive value (неприличное значение) – идентификатор должен намекать на свои действия (роль объекта в программе должна быть ясна из его имени).
- "Consistency" (логичность, последовательность) – у схожих по назначению объектов должны быть схожие имена. Этот пункт канает за чеченский понт (как таковой бессмысленный, бесполезный, рассматривается как эстетическая идея).
- Speed of the decision (и здесь за СПИД, хотя в данном случае имеется ввиду скорость) – имя объекта не должно отнимать у кодера много времени при его эксплуатации: "придумывание, ввод, редактирование и т.д. (не надо вводить в программу идентификатор следующего вида: "ЗдесьЯБудуХранитьТекстЗапроса")."
Не стоит слишком долго пыхтеть над придумыванием новых идентификаторах. Тем более удовлетворяющих все четыре правила. Уж больно это гемороно, особенно если речь идет о "Consistency". Да и по сути нафих нужно. Кто будет ковырять твой код кроме тебя самого. Не правда ли.
Тогда для чего это нужно?
Глупый вопрос, достойный только Левы Баранова. Все под богом мы ходим. Не сегодня-завтра ты сломаешь ногу, руку или того лучше, помрешь. И вот твой код в руках твоего heir (наследника). Как ему бедному разгребать твои каки? Если убедил, то читаем дальше. Нет, бурундук тоже птица пшел крылья искать.
Теперь же поговорим о преимуществе соглашений. Самое главное преимущество это же конечно повышенная читабельность вашего кода, другим программером с которым вы заключите соглашение о правилах присваивание имен объектам программы. В принципе для этого и договариваются. К тому же использование соглашений заметно облегчает этот самый пресловутый think up name variable (придумывание идентификаторов).
А теперь совсем кратко как правила облегчают понимание:
Имена объектов будут мнемоническими. Имеющим строго определенный смысл. Отсюда следует, что назначение объекта будет очевидно для того, кто знает правила построение его имени.
Смысловое значение позволяет отобразить индивидуальное наименование в наборе характеристик.
Использование правил построений наименований позволяет избежать противоречивости в именах объектов.
Построение наименование происходит механически. Что позволяет повысить скорость ввода и редактирования имен на этапе разработки.
Правила.
Известная индейская пословица гласит: "Есть много способов пахнуть скунсом". Смысл ее гораздо прозаичен, чем может показаться на первый взгляд. У любой проблемы есть куча решений. Так и в нашем случае, правил наименования объектов программы может быть много. Каждый должен сам следить за цветом месячных своих подруг. Я здесь лишь приведу свои правила, сформировавшиеся во время моего небольшого личного опыта написания программ в среде одинСи.
Для описания характеристик объекта удобнее всего использовать префиксы. Я использую в основном простые префиксы (префиксом указывается одна характеристика объекта). Достаточно редко, но все же приходится, использую составные префиксы. То есть префикс, состоящий из двух и более простых префиксов. Отсюда. Составные префиксы используются для отображения двух и более характеристик объекта. Сам по себе префикс представляет набор строчных букв и спецсимволов до первой заглавной буквы в персональном имени идентификатора, например: vlMonth (сзМесяц) – где vl (сз) и есть префикс. Количество символов простого префикса не должно быть слишком большим, для повышения скорости его ввода. В то же время не должно быть слишком маленьким, для обеспечения его уникальности при формировании составного префикса. Оптимальный размер префикса 2-3 символа.
Префиксы.
Начнем, пожалуй, с положения объектов, а точнее указания в свойствах объекта возможность обращаться к нему из различных мест программы (конфигурации). Специфика программ написанных на данном языке, во всяком случае, в версии 77, позволяет разместить объекты доступные из любого места в программе только в одном модуле. Который называется "глобальный модуль конфигурации", указав при описании объекта ключевое слово export (экспорт). Вот такие объекты мы будем выделять с помощью самого эксклюзивного префикса – ведущим символом знаком подчеркивания ("_"). То бишь если имя начинается с него, то данный объект конфигурации "глобален".
Объекты… или за процедуры, функции и переменные.
При разработке любого приложения, на любом языке программирования, любой программер может оперировать всего тремя объектами. Это процедуры, функции и переменные. Первые две что-то вычисляют. Последняя что-то содержит. Так уж повелось, что при использовании процедур и функций в тексте программ после имени нужно обязательно указать парные круглые скобки. Независимо от того передаем мы им чего-то или нет. Правда, это больше похоже на суффикс, но в данном случае не важно. Важно другое, что по ним, по скобкам, мы достоверно можем идентифицировать объект. Нет скобок, значит это переменная. Наличие их говорит о том, что это процедура или функция.
Как же нам различать процедуры и функции? А какое самое главное отличие между ними. Правильно. Функция, после того как выполнила вычисления, возвращает результат. Процедура нет.
На основании изложенного можно сформулировать правило. Если в описании объекта программы наличествует парные круглые скобки и префикс типа значения, то данный объект программы является функцией, которая возвращает результат с указанным в ее имени типом значения. Если тип значения не указан, то данное описание соответствует процедуре.
Постойте, скажите вы, а как же быть с одной особенностью 1С. В некоторых случаях, мы не можем вызвать для расчетов процедуру, но при этом результат функции не важен. Как нам отличить процедуру от функции, которая ничего не возвращает. Идем копаться в первоисточники. А точнее в тексты программ написанных на языке Си, где само понятие процедура отсутствует наглухо. Объектом поиска становятся функции типа void ("пустота"). Дальше думайте сами, а я вожу еще один эксклюзивный префикс, для функций которые ничего не возвращают – void ("пст").
Для самих переменных мы используем префикс, указывающий на тип содержащегося в них значения. Правда и здесь есть одно исключение. Иначе, какое это будет правило. Оно касается переменной используемой в теле функции значение, которого функция вернет по завершению своей работы. Что бы эта переменная бросалась сразу в глаза, повышая читабельность кода, я ее всегда описываю одним словом – Answer ("Ответ"). Тип оной соответственно описан в имени функции.
Типы, типы и еще раз типы.
Тут много что можно писать, обсуждая те или иные плюсы. Поэтому я здесь приведу те префиксы, которые использую сам. С кратким описанием того, что это за тип и почему я использую именно такой префикс.
префикс не русский | префикс русский |
тип | комментарий |
| un |
ан | не определен |
от английского unknown и русского аноним |
int | чис |
число | в один си для работы с числами есть только один тип число и он не делятся на целые и дробные, просто я по привычке… integer |
str | стр |
строка | строка она и на чукотке строка… string |
dt | дт |
дата | дата… она же date |
con | кон |
константа | константа как constant |
ref | спр |
справочник | от английского reference (справочник) |
doc | док |
документ | document – документ |
seq | псл |
последовательность | последовательность - это просто "гениальное" изобретение (sequence) |
enm | пер |
перечисление | enumeration – перечисление |
coa | пс |
план счетов | План счетов даже не знаю как по русский это сказать (chart of accounts) |
acc | счт |
счет | счет только не тот, что в банке… account но не доступ |
skd | вс |
вид субконто | что такое вид субконто даже ворд не знает, куда мне грешному (subconto kind) |
opr | опр |
операция | это бухгалтерская операция (operation) |
ent | прв |
проводка | как говорил Пит про_водку не надо писать… ведь это всего лишь бухгалтерский entries. |
reg | рег |
регистр | это register только не тот что в ассемблере, это особый односишный регистр. |
cjl | жр |
журнал расчетов | в журнале расчетов хранятся записи о начислениях и удержаниях сотрудников (calculation journal) |
ckd | вр |
виды расчетов | виды расчетов мой самый любимый объект… из тех что не создаются программно (calculation kind) |
cgp | гр |
группы расчетов | группы расчетов – это собранные в группы виды (calculation group) |
cal | кал |
календарь | календарь – непонятный объект, для чего он нужен и кто его использует (calendar) |
per | пер |
периодический | периодический объект нужен для работы с periodic константами и реквизитами справочников |
vl | сз |
список значений | список значений – набор различных данных в одном объекте (value list) |
vt | тз |
таблица значений | таблица значений самая нака в один си. Ребята, которые ее придумали, наверное, и не догадывались что сотворили (value table) |
tab | таб |
таблица | таблица в основном нужна для формирования печатных форм документов и всяких отчетов |
at> | би |
бухгалтерские итоги | бухгалтерские итоги прародитель "черного" запроса (account total) |
qur | зап |
запрос | запрос – объект для выборки данных (query) |
txt | тхт |
текст | данный объект для работы с файлами стандарта ANSI или по одноэсному текст(text) |
pic | крт |
картинка | картинка – не более чем picture |
cht | дгр |
диаграмма | диаграмма – еще одна плюха в попытке из один си сделать Excel (chart) |
fs | фс |
файловая система | ну а этот объект для работы с файловой системой (files system), если без албанского, то для работы с файлами |
dbf | дбф |
XBase | единственный объект (из штатных) который в один си не имеет русской трансляции, нужен для работы с файлами формата data base files (файлы базы данных) |
md | мд |
метаданные | именно по этому заглавный файл конфигурации имеет такое расширение… для программного получения информации аналогичной той что вы видите когда смотрите на дерево конфигурации в конфигураторе… или метаданные конфы (metadata) |
frm | фрм |
контекст формы | объект для управления окном открытой формы… |
bt | кн |
кнопка | это просто кнопка, по которой кликает пользователь (button) |
cb | чб |
флажок | почему check box одноэсники назвали флажком, не понимаю |
rb | рб |
переключатель | ну с radio button логика их понятна |
vl | сз |
списокполе со списком | в сути этот тот же список значений только нарисованный на форме
|
gb | рг |
рамка группы | рамка группы да вы сами знаете, что это такое group box |
vt | тз |
таблица значений | таблица значений только на форме… есть несколько нюансов у этой value table |
pic | крт |
картинка | картинка на форме ни чем не отличается от picture созданной программно |
arr | мас |
массив | в один си массивы получились такими не кошерными, что их редко кто использует, но нет-нет используют (array)
|
add | вк |
внешняя компонента | объект для работы с подгружаемыми модулями расширения языка один си… внешняя компонента… почему add, да я сам фих знаю… наверное от AddIn |
ole | оле |
OLE | объект, полученный через механизм OLE Automation |
obj | об |
объект | прочие объекты, полученные через недокументированные, но штатные средства один си |
Стилевое оформление текста программ.
В этой части настоящей статьи мы поговорим об "этажерках", комментов и прочей лабе несколько повышающей читабельность сыра. Профессионализм и специализм одноэсников сквозит в 70% виденного мною сыра. И порой, чтобы найти место, в программе приводящее к ошибке приходится львиную часть времени приводить текст в божеский вид. Симонии не уделил этой теме места в своей нотации, наверное, в небезызвестной корпорации работают все-таки программисты, а не специалисты. А зачем на этом заострять внимание, когда это все по дефолту. Другое дело одноэсники. В лучшем случае настоящий одноэсник прослушал курс лекций на языке паскаль (дельфи) или васике. А большинство так, типа мы сами с усами, что нам стоит дом построить, тяпку в руки и вперед. Впрочем, ладно разговор не о них, а о том, как не быть похожими на них. Хотя впрочем, решать вам кто вы – реальный пацан или Лева Баранов.
Язык.
Меня очень часто спрашивают, почему я пишу по-английски, религия что ли. Можно сказать, что да, ведь привычка таже религия. В среду одноэсников я попал случайно. Хотя также случайно из нее вышел. А основным языком общения между мной и машинкой остается язык си, то который с двумя плюсиками. Ну, и даже при программировании в самой среде один эс я часто использовал возможности OLE Automation, а мешанина кода на разных языках, по-моему, не очень комильно.
Еще об одной силе привычки. Когда наоборот одноэсник пишет программу на какой-нибудь дельфи. Забавно смотрятся переменные вида: "celMayPeremenaja", ну или в таком духе. А теперь представим невозможное, что текст программы с такими переменными читаем не мы с вами, а какой-нибудь Билли Гейтс. Вот он усытца вкуривая смысл данных переменных.
Вопреки бытующему мнению, чтобы писать на английском его знать не надо. Я когда написал свою first program кроме god save the queen не фиха не знал. Потом мой словарный запас пополнялся благодаря использованию англо-русских (русско-английских) словарей. И теперь я знаю что-то около 150 английских слов, а может и все 200. Так что совет вырабатывайте свой стиль сразу, в жизни пригодится.
И еще один довод в пользу английского. Он достаточно емок и компактен. Букв приходится меньше набирать. Короче самый оптимальный язык для ленивых (интересно, а другие бывают) программистов.
Комменты.
Ох уж эти комменты. Споры тут идут давно. Одни считают, что они как масло каши не испортят, другие наоборот. Я не придерживаюсь ни какой строгой концепции в этом вопросе. И наличие комментов в теле зависит от того для чего данное тело нужно. Если это пример того, как надо, или не надо делать, то комментов может быть больше чем самого кода. В противном случае оставляю только два вида комментариев. Своеобразные пояснительные записки. Один в начале модуля, другие перед началом процедуры или функции.
Цель первого, того, что в начале модуля, больше копирайтная. В нем указывается для чего собственно данный модуль и написан. Пример:
//*******************************************
//
// Краткое описания и назначение модуля.
//
// Name: Имя модуля.
//
// by Автор
// Место, Месяц и Год создания
//
// information for contact:
// mailto, icq, phone и прочая лаба
// для вашего быстрейшего поиска.
//
//*******************************************
Следующий вид комментариев предназначен для описания процедуры или функции. Пример:
//*******************************************
// МояПроцедураИлиФункция()
//
// Параметры:
// Полное описание всех переданных параметров
// и их назначение. Если таковые есть.
//
// Возвращаемое значение:
// Полное описание того что вернет функция.
//
// Описание:
// Краткое описание того, что делает процедура или функция
//
function МояПроцедураИлиФункция()
Если к модулю прилагается подробное описание всей работы в отдельном файле, то данный вид комментариев можно опустить, то есть не писать.
Есть еще один вид комментарий, который важен, если вы работаете над большим проектом или в команде. Так называемые пуки. Нужен он для того, чтобы понять, кто и куда в туалет ходил. Обычно ставятся в самом начале модуля, сразу после копирайтов, и имеют приблизительно такой вид:
//*******************************************
// Pack Номер пука
//
// by Автор
// Место, Месяц и Год создания пука
//
// information for contact:
// mailto, ICQ, phone и прочая лаба
// для вашего быстрейшего поиска.
//
//*******************************************
// Изменения
//
// Полное описание всех внесенных изменений.
// Добавлена переменная, функция или процедура.
// Исправлена ошибка в такой то процедуре или функции.
//
//*******************************************
В сами места исправлений отмечают конструкцией вида:
//*******************************************
// Pack Номер пука.
//*******************************************
// Здесь идут ваши исправления.
// Рекомендую ни когда не удалять из тела исправленные куски кода, опускайте их в комменты. Да бы потом // можно было сделать ролл бак.
//*******************************************
// end of pack
//*******************************************
Зарезервированные слова.
Зарезервированные слова всегда должны быть в нижнем регистре, для прапорщиков СА – это те слова, которые красятся в красный цвет. Как ни странно это правило действует и для паскалистов, смотри Object Pascal Style Guide(http://edn.embarcadero.com/article/10280), но именно они его чаще всего и нарушают. Хотя, что с них взять, достаточно посмотреть для чего этот самый паскаль был придуман.
Использование пробелов.
Так уж исторически сложилось, что основная функция пробела это разделение отдельных слов. Что же в теле программы является отдельным словом. Конечно это зарезервированные слова, операции и операнды. Поэтому использование пробела в следующих случаях категорически запрещено:
- До и после оператора точка (при указывании свойств и методов объектов).
- Между открывающей скобкой и именем процедуры, функции и методов объектов.
- После открывающей или перед закрывающей, как круглой, так и квадратной.
- Перед точкой с запятой.
Не рекомендуется использовать вместо пробела символа табуляции или множества пробелов.
Использование символа подчеркивания.
Использование символа подчеркивания вместо пробела для отделения слов и префиксов в именах переменных, функций и процедур запрещено, так как он служит префиксом глобальности. Используйте вместо этого буквы верхнего регистра.
Использования символа табуляции.
Данный символ используйте только для выделения логических блоков внутри процедур, функций, циклов и условных операторов. Так называемая этажерка. Во всех остальных случаях использования данного символа запрещено.
Использование цифр в именах переменных.
Использование цифр в именах переменных тоже не есть хорошо. Иногда волосы дыбом встают при взгляде на некоторые бесценные творения. Но не хватает у вас ума придумать персональный идентификатор для группы однотипных переменных, засуньте их лучше в массив. Что даже вам несколько упростит работу с ними.
За операторы goto, break and continue
Данные операторы вне закона были объявленные еще при процедурном программировании, не говоря за объектно-ориентированное. Использовать их или нет, пусть вам подсказывает ваша линейная логика. Последних два я нет-нет использую, когда ломает продумывать условия выхода из цикла.
Заключение.
Данная статья не претендует на роль стандарта де-факто. Хочешь имеешь, хочешь нет. Ведь сколько людей, столько мнений. И кому-то нравиться рисовать тупым карандашом, а кому-то острым. Тем боле в большинстве компаний утвержден свой стиль. Это с одной стороны хорошо. Не фиха выдумывать не приходится, а с другой стороны. Пока научишься тупым карандашом рисовать тонкие линии, все пальцы себе обломаешь. |