Раздел: Компьютерная документация -> Программирование -> Basic

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

При разработке программного продукта коллективом программистов существует такое понятие как coding conventions - соглашения о стиле кодирования. Это единый набор правил определяющий принципы выбора имён переменных, форматирования исходных текстов программ, использование комментариев и т.п. Хотя эти соглашения являются индивидуальными для каждого коллектива и даже для каждого проекта, однако можно выделить некоторые универсальные устоявшиеся положения, которые составляют хороший стиль оформления кода.
Однако единый стиль программирования необходим не только при коллективной разработке. Применение принципов описанных в данной статье позволит сэкономить некоторое количество сил и времени при разработке и ваших программ даже если вы пишете в одиночку.
Многие начинающие программисты скептически относятся к такого рода рекомендациям, считая что их код и так прост и понятен. К сожалению зачастую это не так. Запомните: если в вашей программе больше трёх строк кода - пора задуматься о его правильном оформлении.
Ведь ваш стиль оформления кода - это ваш электронный почерк. Давайте писать красиво!

Материал статьи ориентирован в первую очередь на язык Microsoft Visual Basic, однако может быть с некоторыми ремарками распространён и на другие языки программирования.
Статья расчитана в первую очередь на программистов уже имеющих знакомство с языком, но не имеющих опыта реального программирования и ещё не имеющих устоявшегося стиля написания кода. Хотя возможно будет небезынтересна и опытным программистам.

Всё написанное является личным мнением автора и не в коей мере не претендует ни на оригинальность, ни на абсолютную истинность.
Замечания и пожелания приветствуются.


1. Используйте осмысленные имена переменных, функций, элементов управления, классов и модулей.
Это первое с чем необходимо бороться начинающему (а иногда к сожалению и опытному) программисту. Дело в том, что если в момент написания вы помните для чего используется каждая переменная, то уже при следующем просмотре бывает сложно восстановить назначение и смысл некоторых переменных. А человеку которому вы захотите показать свой код и того трудней разобраться в нагромождении кучи переменных a, b, c, x, y, kkk, hjd и qwerty.
Имя переменной должно говорить само за себя. При одном взгляде на хорошо названную переменную становится очевидно не только предназначение, но и её тип, область видимости и её особенности.
Плохо: a, b, bb, bbb, b1, text1.
Хорошо: MessageText.

2. Используйте отступы.
Отступы - это символы пробелов или табуляции, вставляемые перед в начало строк которые лежат внутри конструкций которые имеют отрывающий и закрывающий оператор. В vb это If...Then...Else...End If, Do Until/While...Loop, For...Next, а также открытие и закрытие файлов Open...Close(...).
Не обсуждается. Отступы должны быть. Это наиболее простой и эффективный способ отразить структуру и вложенность операторов в вашем коде.
Сколько именно пробелов или символов табуляции вставлять не принципиально. Однако следует помнить, что в случае небольшого отступа (1-2 пробела) структура блоков кодов видна плохо, сводя на нет весь смысл отступов. А в случае больших отступов (больше 8 пробелов) при большой вложенности операторов строки начинают "вылезать" за правую границу окна редактора, и приходится прокручивать его горизонтальной полосой прокрутки. На мой взгляд оптимальным является величина в 4 пробела или 1 символ табуляции. Примечание: в vb6 для формирования отступов можно пользоваться клавишей Tab, но редактор преобразует эти символы табуляции в пробелы. Задать количество символов пробела на один Tab можно в Tools -> Options -> Editor -> Tab Width.
Плохо:

Код:

If frmMain.Visible Then frmMain.Hide Else frmMain.Show End If

Хорошо:

Код:

If frmMain.Visible Then     frmMain.Hide Else     frmMain.Show End If

3. Не используйте русские или иные национальные символы. Не используйте в качестве имён транскрипции русских (национальных) слов.
Vb один из немногих языков в котором разрешены имена в которых присутствуют символы из верхней кодовой таблицы (символы с ASCII-кодами свыше 127). Однако я бы не рекомендовал пользоваться этой возможностью. Так как это автоматически делает невозможной работу с вашим кодом для людей не владеющих русским языком или не имеющих русских шрифтов и русской раскладки клавиатуры. Имена получаются субъективно "некрасивыми". Кроме того, никто не гарантирует, что в одной из следующих версиях языка Microsoft не уберёт поддержку идентификаторов с национальными символами.
Что касается транскрибированных имён идентификаторов (например "peremennaya"), то это тоже не лучший выход. По тем же причинам - невладение языком, "грязность".
Так уж сложилось, что традиционно в программировании используются латинские символы, поэтому для таких системных вещей как имена идентификаторов следует использовать английский алфавит.
Плохо: txtЛогин, Проверка(), МассивФамилий, StrokaPoiska.
Хорошо: txtLogin, Check(), NamesArray, SearchString (про префиксы см. далее).

4. Не используйте имена элементов управления по умолчанию.
Этот совет имеет непосредственное отношение к пункту об осмысленных именах переменных. Если будете использовать имена по умолчанию, то вы очень быстро запутаетесь какое из 15 TextBox с номерами отвечает например за ввод имени пользователя.
Исключение: если вы задаёте вопрос на форуме и приводите образцы своего кода с просьбой попробовать его, или наоборот приводите код в качестве ответа, то имеет смысл использовать именно имена по умолчанию. Это связано с тем, что, во-первых, человеку который будет вставлять ваш код в редактор vb необходимо будет добавить форму и требуемые элементы управления и переименовывать их. Во-вторых, из имён не всегда очевиден тип элементов управления, а имена по умолчанию, как правило, совпадают с их типом (дополненные номером).
Плохо: Form1, Textbox2, ListView15.
Хорошо: frmMain, txtName, lvwListOfCommands (про префиксы см. далее).

5. Используйте префиксы типов.
Префиксы типов (так называемая венгерская нотация) - это определённые символы в начале имени переменной, которые в закодированном виде несут информацию о переменной. Общепринятыми являются следующие префиксы:
s или sz - переменная типа String
b - Byte или Boolean
i - Integer
l - Long
d - Double
s - Single
d - Date
o_ - объект
e - перечислимый тип (Enum)
g_ - глобальная переменная (Public)
m_ или loc_ - локальная переменная (Private)
и т.д.
Для элементов управления на форме:
txt - TextBox
pic - PictureBox
lbl - Label
fr или fra - Frame
tvw - TreeView
и т.д.
Для модулей:
frm - форма
mod - модуль
cls - модуль класса

Однако, следует заметить, что нет единого мнения о полезности такой записи. С одной стороны при одном взгляде на такую переменную сразу видно её особенности. С другой стороны не существует определённого стандарта такого именования, приходится производить дополнительные телодвижения при наборе имён переменных, это "уродует" имя переменной.
Лично я *всегда* использую префиксы типов только в именах элементов управления и модулей и в некоторых случаях в именах обычных переменных в особо запутанных местах.
Вы также можете "изобретать" свои префиксы. Но делать это следует осторожно и только в тех случаях, когда польза от этого перевешивает недостатки. Например в некоторых типовых случаях перед именами временных промежуточных переменных я ставлю префикс t_, в переменных получающих входную информацию in_, выходную out_.
Пожалуй сюда же следует отнести ещё один подход, хоть он и не имеет отношения к префиксам, но весьма полезен. Для типовых переменных используйте одинаковые имена. Например, перед открытием файла для хранения номера файла возвращаемого функцией FreeFile использовать переменную с именем ff. Таким образом, встречая в коде переменную ff, сразу становится понятно для чего она используется.
Плохо: lokalnaya_filename, FileName, InternetClass.
Хорошо: m_filename, txtFileName, clsInternet.

6. Капитализация vs подчёркивание.
В случаях когда имя идентификатора состоит из нескольких слов для удобства чтения их следует как-то разделить. Для этого есть два основных способа.
Капитализация - первая буква каждого слова в имени переменной записывается с заглавной буквы, остальные строчными.
Подчёркивание - слова разделяются символами подчёркивания "_".
Какой из двух способов предпочесть - дело вкуса. Однако могу порекомендовать следующий принцип: в именах локальных или промежуточных переменных используйте подчёркивание, в глобальных переменных (глобальных на уровне модуля или приложения) - капитализацию. Во-первых: капитализованные переменные выглядят более "солидно" и это выделяет их в коде. Во-вторых: это позволяет визуально различать переменные по области видимости и позволяет отказаться от использования префиксов области видимости (g_ и m_ - см. пункт о префиксах типов). Вы можете использовать любые другие схемы, если они кажутся вам более логичными и облегчают чтение и понимание кода.
Плохо: filenameslist, sfilenameslist
Хорошо: filenames_list, FileNamesList, sFileNamesList.

7. Пишите комментарии.
Старайтесь по возможности писать комментарии. Если вы покажете кому-то свой код, то ему будет намного проще сориентироваться в нём, если там будут подсказки в виде комментариев. Даже если вы не собираетесь ничего никому показывать всё равно следует писать комментарии. Так как просматривая свой код уже через месяц вы будете с трудом вспоминать что и как у вас работает и зачем нужен тот или иной кусок. Комментарии выступают как своеобразные записки (как говорит наш уважаемый администратор Bit "писюльки" :] ) самому себе на будущее.

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

Код:

Public Function CalcCheckSum(ByRef x() As Long) As Long ' Расчёт контрольной суммы ' Вход: '    x() - последовательность для которой вычисляется контрольная сумма ' Выход: '    значение контрольной суммы, алгоритм - crc32 ' Особенности: '    - аргумент x() передаётся по ссылке для экономии памяти - соблюдать осторожность '    - использует загруженную ранее таблицу crc_table ... End Function

Однако следует избегать и чрезмерного и бессмысленного комментирования.
Плохо:
' записываем в переменную c значение равное сумме переменной a и переменной b (слишком развёрнуто, очевидно из кода и без комментариев)
c = a + b
Хорошо:
' расстояние от начала координат до точки (лаконично, отражает суть)
r = Sqr(x * x + y * y)

В основном, все признают необходимость комментариев. Но на практике выполняют это условие немногие. Причина банальна - лень. Чтобы это не было таким скучным занятием можете развлекать себя, например, если вы любите ascii-art, то можете каждый комментарий заключать в красивую рамочку с использованием псевдографики. Неплохим вариантом является написание комментариев по-английски - заодно и язык подучите. Можете писать комментарии на сленге (один мой приятель как-то рассказал, что в фирме в которой он работал, обратили его внимание на то, что он пишет комментарии в "падонскам" стиле). Хотя я всё же по очевидным причинам не рекомендовал бы писать комментарии с использованием непечатной лексики.
Запомните - плохие комментарии лучше, чем вообще никаких.

8. Используйте одинаковую индексацию.
Как правило массивы индексируют начиная с 0 или 1. У обоих подходов есть свои достоинства и недостатки. Вы можете использовать тот который вам больше нравится. Но всегда используйте только эту индексацию. По крайней мере в рамках одного проекта. Это избавит вас от необходимости перед каждым массивом или коллекцией мучительно вспоминать, а потом и метаться по коду выискивая какой же индекс у вас имеет первый элемент 1 или 0.

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

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

Автор: Chan
Источник: www.bit.pirit.info/forum/

Ссылки по теме

Вызов функций по указателю

Техника программирования сложных окон в Visual Basic

Создание программы на Visual basic для вывода случайного числа в заданном интервале чисел

Visual Basic и Системный Реестр Windows

Встроенные функции VisualBasic

Вся документация по Visual Basic

Компьютерная документация - Главная