Комментарии в коде

Обновлен: Ноябрь 2007

В примерах кодов часто встречается символ начала комментария ('). Этот символ дает компилятору Visual Basic инструкцию проигнорировать последующий текст, именуемый комментарием. Комментарии — это краткие заметки, внесенные в код, чтобы сделать чтение кода более легким.

Хорошим стилем программирования считается начинать все процедуры с краткого комментария, описывающего функциональные характеристики процедуры (то, что она делает). Это необходимо для вашего собственного удобства и удобства того, кто читает этот код. Следует отличать детали реализации (как процедура работает) от комментариев, описывающих функциональные характеристики. Если в комментарий включены детали реализации, их следует обновлять при редактировании кода.

Комментарии могут располагаться в конце той же строки, где содержится оператор, или занимать отдельную строку. Оба способа представлены в следующем коде:

' This is a comment beginning at the left edge of the screen.
text1.Text = "Hi!"   ' This is an inline comment.

Если комментарий занимает более одной строки, каждая строка должна начинаться с символа начала комментария, как показано в следующем примере.

' This comment is too long to fit on a single line, so we break 
' it into two lines. Some comments might need three or more lines.

Правила комментирования

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

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

Также рекомендуется принять во внимание следующие моменты.

• Объявление каждой важной переменной должно предшествовать комментарию, описывающему ее назначение.

• Имена переменных, элементов управления и процедур должны быть функционально понятными, чтобы комментарии требовались только в случае особо сложных деталей реализации.

• Комментарии не могут располагаться за последовательностью продолжения строки в той же строке.

Символы начала комментария можно добавлять или удалять для целых блоков кода. Для этого следует выделить одну или более строки и нажать кнопку Comment () или Uncomment () в панели инструментов Edit.

Примечание.
Кроме того, можно добавить в код комментарии, поставив в начале текста ключевое слово REM. Однако использование символа ' и кнопок Comment/Uncomment существенно проще, а также требует меньше места и памяти.

См. также

Ссылки

Оператор REM (Visual Basic)

Другие ресурсы

Соглашения о структуре программы и коде