Комментарии в языке программирования - это специальная конструкция языка программирования, позволяющая записывать текстовую информацию, которую компьютер не будет воспринимать как команды кода. Комментарии игнорируются при выполнении программы и предназначены исключительно для разработчиков. Это инструмент, облегчающий работу программиста. Комментарии, обычно, описывают работу того или иного фрагмента кода, обосновывают то или иное решение, принятое программистом при написании программы (особенно это важно, если решение нестандартное). Впрочем, конечно, есть и те, кто привык избегать комментирования в коде или даже объявляет практику комментирования кода вредной (аргументируя это тем, что хороший код должен быть понятен и без комментариев). Естественно, что при комментировании кода надо знать меру. Врядли стоит комментировать каждую строчку вашей программы.
ActionScript (и ActionScript 2.0, и ActionScript 3.0) поддерживает два вида комментариев:
1.) Однострочные (простые) комментарии.
Однострочный комментарий имеет следующий вид:
Код ActionScript:
// это однострочный комментарий
var i:int = 0; // ещё один однострочный комментарий
/////////// это тоже однострочный комментарий
Однострочный комментарий начинается с двойной косой черты (//). Всё, что находится после двойной косой черты и до конца строки, является комментарием и игнорируется компьютером.
2.) Многострочные (блочные) комментарии.
Многострочный комментарий имеет следующий вид:
Код ActionScript:
/*
это
многострочный
комментарий
*/
var i:int = 0; /* многострочный комментарий могут записать и в одну строчку */
Многострочный комментарий начинается маркером /* и заканчивается маркером */. Всё, что находится между этими маркерами, является комментариями. Надо быть внимательным при использовании многострочных комментариев и не забывать их вовремя закрывать.
Вложенные многострочные комментарии в AS недопустимы.
Код ActionScript:
/*
/*
trace('Привет!')
*/
*/
Вышеприведённый комментарий вызовет ошибку.
Однострочные и многострочные комментарии можно использовать совместно. На этом основаны так называемые переключаемые комментарии. Пример следует.
Код ActionScript:
//*
trace('Привет!')
/*/
trace('Пока!')
*/
/*
trace('Привет!')
/*/
trace('Пока!')
/*/
Как видите, изменяя положение всего одной косой черты, мы закрываем один блог кода и открываем другой. В этом и суть переключаемых комментариев.
Функции комментариев весьма многообразны, но в качестве основных можно выделить следующие:
1.) Документирование кода.
Желательно всегда комментировать код, даже если он ваш и довольно простой. Ведь всегда есть вероятность, что вам в будущем придётся вернуться к этому коду и может быть потрачено драгоценное время на воссоздание в памяти всех нюансов написанного вами же приложения. А в некоторых случаях комментарии становятся просто обязательными:
- если код очень большой по размеру (например, он может включать десятки классов и просто вспомнить что и за что отвечает - задача сверхсложная);
- если предполагается, что впоследствии с данным кодом будут работать другие программисты.
Отдельный случай - комментарии к коду, рассчитанные на специальные программы, генерирующие на основе данных комментариев документацию для разработчиков. Такие комментарии (их ещё называют документирующими комментариями) имеют особые правила оформление.
2.) Заголовки файлов классов.
Так, например, FlashDevelop при создании нового класса сразу же создаёт и многострочный комментарий, который размещает до тела класса.
Код ActionScript 3.0:
/**
* ...
* @author edapskov
*/
В этом комментарии-заголовке может размещаться различная информация: указание на авторство, описание класса, пример использования класса, время создания и последней модификации класса, лицензия и прочее. Вот один из возможных шаблонов с подробной информацией о классе.
Код ActionScript 3.0:
/** ----------------------------------------------------------
* Class Name
* -----------------------------------------------------------
* Description:
* ----------------------------------------------------------
* Created by:
* Modified by:
* Date Modified:
* ----------------------------------------------------------
* Copyright ©2007 Sposto Interactive (Sposto Productions, LLC)
* For license and usage information, please submit and inquiry
* at http://www.sposto.com/contact/1/1.html
* ----------------------------------------------------------
*/
3.) Отладка и тестирование кода.
Интересный момент - комментирование кода иногда сравнивают с ведением личного дневника. Личный дневник имеет замечательное психотерапевтическое действие - он позволяет чётко и ясно сформулировать проблему, а правильно озвученную проблему гораздо проще решить. Точно так же происходит и в случае с комментариями. Комментирование позволяет правильно поставить вопрос, сформулировать возникшую трудность. После этого её гораздо проще решить самому или обратиться за помощью к другим разработчикам.
Кроме этого, комментарии часто используются для поиска ошибок в коде.
4.) Отключение фрагментов кода.
Зачем оставлять в программе неиспользуемый код и помещать его внутрь комментариев? Ну, причины могут быть разные. Возможно, автор рассчитывает позднее вернуться к данному коду, чтобы дополнить или изменить. И в этом случае закомментированный фрагмент выполняет функцию своеобразного "черновика" для программиста.
5.) Блокировка альтернативных решений.
Иногда возникают ситуации, когда ту или иную задачу можно решить несколькими способами. При этом программист может поместить альтернативный способ решения в комментарии. И если позднее сам программист или кто-то другой решит воспользоваться именно альтернативным решением, то надо будет просто его раскомментировать, а старое решение, наоборот, поместить в комментарии.
6.) Структурные комментарии.
Структурные комментарии - это комментарии, которые используются для отделения одного блока кода от другого. Комментариями они часто являются чисто условно, так как могут вообще не содержать текст. Но зато с помощью структурных комментариев облегчается чтение кода и навигация по коду.
Код ActionScript:
// данный блок кода выводит "Привет!"
trace("Привет!")
/*
данный блок кода выводит "Пока!"
*/
trace("Пока!")
//////////////////////////////
trace("Прощай!")
//----------------------------
Стилистические особенности оформления комментариев
У программистов, как и у всех людей, есть свои привычки, которые могут распространяться даже на такую жизненную мелочь, как комментирование своего кода. Часто это обусловлено образованием или опытом работы с другими языками программирования. Для примера можно привести комментарий в стиле PHP.
Код ActionScript 3.0:
/*#################################
## Bold Comment ##
#################################*/
Скорее всего, такой стиль ведения комментариев автор унаследовал из практики работы с языком PHP.
Ну, не знаю как вам, а мне, после написания данного поста, гораздо яснее стал смысл и назначение комментариев к коду:-)
Рейтинг поста: 
