Иногда нужно оставить скрытую заметку или пояснить что-то в коде человеческим языком. Такое примечание пригодится и себе в будущем, и следующим разработчикам, которые будут работать над вашим проектом. Именно для этого изначально были придуманы комментарии! Вся их прелесть в том, что пользователи их никогда не увидят. Это секретная почта для разработчиков
Для комментариев находится и более утилитарное применение: скрывать блоки кода со страницы, не удаляя их из файла.
Пример
Скопировать ссылку «Пример» Скопировано
Привет! Я комментарий в HTML-коде, меня не видно на странице—>
Я — обычный текст. Меня видно на странице!
p>Я — обычный текст. Меня видно на странице!p> Скопировать Скопировано Не удалось скопировать
Как пишется
Скопировать ссылку «Как пишется» Скопировано
В HTML возможен только один тип комментариев, в отличие от комментариев в CSS и JS.
Комментарий всегда должен начинаться с конструкции . Тем самым мы чётко показываем браузеру границы спрятанного послания. Профит! Ваш комментарий готов.
Страдания блогера (что мне пишут в личку)
При помощи ровно тех же конструкций мы можем временно спрятать блок кода.
Подсказки
Скопировать ссылку «Подсказки» Скопировано
Содержимое комментария может быть любым, но спецификация перечисляет конкретные ситуации, в которых браузеру будет сложно понять: это содержимое комментария, или он закрывается?
Нельзя вкладывать один комментарий в другой. Да и зачем?
Комментарии не работают внутри тега , но там вообще никакие теги не работают, так что неудивительно.
Чтобы быстро закомментировать или раскомментировать текущую строку или выделенный блок кода, в большинстве редакторов можно нажать Ctrl / или Cmd / .
На практике
Скопировать ссылку «На практике» Скопировано
Алёна Батицкая советует
Скопировать ссылку «Алёна Батицкая советует» Скопировано
Комментарии часто используют, чтобы пометить начало какого-то крупного куска кода, пояснить его назначение. Комментарии, как правило, внешне отличаются от остального кода. Гораздо удобнее просканировать код, пробежаться глазами по комментариям и найти нужную часть, чем вчитываться в сам код.
Комментарий — твой хороший друг
Иногда для подключения чего-нибудь на страницу требуется скопировать-вставить блок кода, написанного не тобой. Чаще всего блок кода сопровождается комментариями. Всегда копируй весь код вместе с этими комментариями и вставляй его к себе в неизменном коде. Тебе же будет проще потом понять, что эта за странная конструкция и зачем она тут нужна.
Например, для подключения Яндекс.Метрики к сайту нужен такой код:
(function(m,e,t,r,i,k,a); m[i].l=1*new Date();k=e.createElement(t),a=e.getElementsByTagName(t)[0],k.async=1,k.src=r,a.parentNode.insertBefore(k,a)>) (window, document, «script», «https://mc.yandex.ru/metrika/tag.js», «ym»); ym(id, «init», clickmap:true, trackLinks:true, accurateTrackBounce:true >); script> (function(m,e,t,r,i,k,a)m[i]=m[i]||function()(m[i].a=m[i].a||[]).push(arguments)>; m[i].l=1*new Date();k=e.createElement(t),a=e.getElementsByTagName(t)[0],k.async=1,k.src=r,a.parentNode.insertBefore(k,a)>) (window, document, «script», «https://mc.yandex.ru/metrika/tag.js», «ym»); ym(id, «init», clickmap:true, trackLinks:true, accurateTrackBounce:true >); script> noscript>div>img src=»https://mc.yandex.ru/watch/id» style=»position:absolute; left:-9999px;» alt=»»>div>noscript> Скопировать Скопировано Не удалось скопировать
Видишь, он начинается с комментария и комментарием заканчивается? Это удобно, визуально отделяет код метрики от остального кода. В дальнейшем тебе проще будет его найти.
БОТАН ЖЖЕТ В ЧАТ РУЛЕТКЕ | Донат в описании
Читая чужой код, обращай внимание на комментарии. Там могут скрываться важные детали и подсказки, которые помогут тебе понять, как этот код работает и почему именно так.
Комментарии видны в браузере в инструментах разработчика, поэтому в них надо писать только документацию, которая поможет работе с кодом. Планы, впечатления и мнения стоит оставить в недоступном для конечных пользователей месте.
Источник: doka.guide
Комментарии в коде — полезные, бессмысленные, вредные?
Как-то проглядывая код некоторых старых модулей, вновь подумал о роли комментариев. Вопрос хоть и тривиальный и обсужденный миллионы раз в книгах, блогах, статьях и форумах, а все-таки подчас задевает за живое. При этом, о пользе комментариев пишут гораздо чаще, чем о их вреде.
Поэтому я выскажу несколько немного провокационных утверждений, затем попробую подкрепить их примерами. Посмотрим что получится. Написанное относится как к (Java) Doc, так и к обычным комментариям в коде.
1. Комментарий может быть полезным, бессмысленным или вредным.
2. Если комментарий не несет явно видимой пользы, то он скорее всего вреден.
3. Комментарии бесполезны / вредны чаще, чем кажется. Отсутствие комментария лучше, чем бесполезный комментарий.
4. Перед тем, как написать комментарий — подумайте дважды, а может не стоит? 🙂
(5. После того, как вы решили, что комментарий все-таки не нужен, посмотрите трижды — а код точно кристалльно понятен?:))
Про полезные комментарии все ясно. Когда:
— достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой
— в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт)
— комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath)
— в комментарии дан короткий ясный пример использования (особенно, если это какой-нибудь custom Ant task или что-то подобное),
то это почти наверняка полезный, а подчас необходимый комментарий.
А теперь посмотрим на некоторый другой часто встречающийся пример.
Такой комментарий обычно создается IDE по умолчанию при генерации геттеров-сеттеров для поля объекта (в свой очередь, если бы в Java были свойства, и необходимые синтетические методы генерились компилятором прозрачно для программиста, этой проблемы бы тоже не было :)).
- /**
- * return the enterpriseName
- */
- public String getEnterpriseName()
- return enterpriseName;
- >
Комментарий, очевидно, не нужен. Ничего нетривиального в коде нет, комментарий по сути дублирует код. Кроме того — комментарий здесь занимает три строки в редакторе кода. Т.е. ровно столько же, сколько и сам код. Мало того что сам код, по сути, синтетический, + из-за Java Code Conventions растягивается три строчки ради удобочитаемости, так еще и комментарий отъедает место.
Java и так маловыразительный язык (с точки зрения среднего количества полезных действия на строку кода) по сравнению с, например, Ruby или Groovy, так зачем тратить экранное место под лишние комментарии.
Тут, конечно, есть тонкий момент. Если код с подобными комментариями — это часть public API какой нибудь generic библиотеки, и никто из пользующихся ей программистов почти никогда не смотрит ее исходники, а смотрит Javadoc — тогда это еще нормально. Но если этот код находится в каком нибудь модуле, разработываемом нами, и исходники этого класса смотрят чаще, чем документацию к нему (что почти всегда верно) — тогда это ИМХО, тот случай, когда правило «любой элемент API должен иметь комментарий» должно применяться с большой осторожностью.
Рассмотренный пример часто дополнительно ухудшается тем, что в комментарий запихиваются теги param, return, которые часто полезной информации не несут, а вот место съедают. Например:
/**
*
* Some description.
* param paramName1 paramName1
* param paramName2 paramName2
* param paramName3 paramName3
* return the name of user
*/
public String getUserName(String paramName1, int paramName2, int paramName2) /* какой то простой прямолинейный код*/
>
(Забавно, что часто в коде есть такие бессмысленные комментарии, а в реально сложных частях комментариев мало :))
И напоследок еще пример.
// Временный хак, т.к. возможность сделать нормально сейчас не поддерживается,
// а сделать надо срочно. По совету [senior developer name], хакнул так.
// 21/04/2004, [developer name].
В некоторых примерах я частично утрирую, но общая идея от этого не меняется.
Updated:
По просьбам в комментах, даю ссылку на пару книг, которые полезно прочитать любому программисту, чтобы не писать таких комментариев (и не делать многих других ошибок)
Источник: habr.com
Комментарии в программе
Комментарии в приложениях играют почти такую же важную роль, как и программный код. Комментарии помогают понять, какую задачу выполняют строка программы, процедура, модуль или все приложение. Они неоднократно встречались в примерах многих уроков. Самый очевидный признак комментария — символ «апостроф» (‘) в начале строки.
Весь текст справа от этого символа (если он не входит в строковую константу) представляет собой комментарий и выводится другим цветом. По умолчанию для комментариев используется зеленый цвет. Использование комментариев — дело привычки и стиля, однако в последующих разделах приведены некоторые рекомендации по поводу эффективного документирования программ. Начнем с документирования на уровне приложения.
Уровень приложения
Недавно один из моих коллег предложил мне задачу. Его интересовал следующий вопрос: как проще всего узнать, какие нестандартные элементы необходимы для нормальной компиляции и работы приложения? Казалось бы, ответить очень просто, ведь приложение написано вами, не так ли? Однако в данной ситуации это были не так.
Программисты разделились на группы для работы над разными проектами, и в каждой группе использовалась своя система построения — центральный компьютер, на котором устанавливались все нестандартные элементы, а также различные версии Visual Basic.
Проблема с компонентами была особенно важной из-за того, что программа установки не всегда могла определить наличие всех необходимых ресурсов, особенно в трехуровневой архитектуре «клиент — сервер». В результате мы решили создавать отдельный программный модуль, который не содержал ничего, кроме сведений о проекте в следующем формате:
После заполнения всех полей комментарий должен выглядеть примерно так:
‘ Имя приложения: Программа для работы с файлами журналов
All Rights Reserved
‘Товарные знаки: Нет
‘Автор/организация: Джейн Доу/АВС Software
‘Назначение: Приложение читает и анализирует файлы журналов.
‘Может использоваться для централизованного управления системными журналами через единый интерфейс с общим набором инструментов
Клиент: Windows 95 / Windows NT 4.0
Сервер: MS SQL Server 6.5
MS Transaction Server 2.0
Файл с комментариями включается в приложение. Если кому-нибудь потребуется проверить приложение, из файла с описанием проекта можно узнать, что необходимо для успешной компиляции и работы приложения. Сначала эти файлы приходилось создавать вручную, но потом я написал специальную надстройку, которая автоматизировала выполнение этой задачи. Эта надстройка рассматривается в уроке 16, «Расширение IDE c помощью надстроек».
ПОДСКАЗКА Если приложение использует нестандартные компоненты или предъявляет какие-либо особые требования (например, наличие сервера баз данных), в проект следует включать подобный файл с комментариями. Для этого файла всегда следует выбирать стандартное имя, чтобы все разработчики точно знали, где можно получить спецификацию приложения.
Уровень модуля
Описание всех программных модулей, входящих в проект, может оказаться не менее важным, чем документирование конкретных деталей и требований всего приложения. Такие описания становятся особенно актуальными в ситуациях, когда центральные программные модули, выполняющие особые функции приложения, используются в нескольких рабочих группах.
Ниже показан стиль комментариев, которыми я предпочитаю пользоваться на уровне модулей. В них содержится вся основная информация, необходимая для использования модуля в приложении. Комментарии сокращают время разработки и обеспечивают последовательный, стандартный вид приложения.
Готовый комментарий выглядит примерно так:
‘Имя файла: NETAPIs.cls
‘Дата: 6 июня 1998 г.
‘Описание: Библиотека содержит объявления и константы
‘сетевых функций Win32 API. Оболочки, оформленные в виде открытых ‘свойств и методов, избавляют программистов от необходимости ‘осуществлять преобразование символов из кодировки ANSI в Unicode.
‘Дата создания библиотеки.
Добавлены процедуры для работы с контроллером домена, а также функции для глобальных пользователей и групп. 8-14-98 Добавлены функции проверки локальных пользователей.
ПОДСКАЗКА Если ваш код предназначен для многократного использования, включите в секцию модуля (General)(Declarations) комментарий с описанием процедур модуля, а также требований или зависимостей данного модуля. В этом случае другим программистам будет проще узнать, какие условия необходимы для работы вашей программы.
Уровень процедуры
Комментарии следует включать и в начало всех нестандартных или нетривиальных процедур и функций. При наличии комментария вам или другим программистам будет проще понять или вспомнить, что делает процедура и как она работает. Например:
‘ Дата: 6 января 1998 г.
‘Описание: Функция добавляет глобального пользователя в домен
‘Требования: Для работы данной функции необходимо
задать значения свойств UserID и Password.
Обратите внимание на поле с именем автора. Я предпочитаю включать его в комментарий, чтобы другие программисты знали, к кому обращаться, если в программе возникнут проблемы. Кроме того, вы сможете обратиться к автору с вопросами относительно данной процедуры.
Уровень программы
Существуют комментарии и более низкого уровня — они включаются непосредственно в программу. Обычно они используются в тех случаях, когда некоторая строка кода требует особого внимания. Благодаря своему коллеге Скотту я начал использовать особую форму комментариев, которая упрощает процессы документирования и отладки (особенно в условиях рабочих групп). В следующей таблице приведены некоторые из этих комментариев.
| Обозначение | Описание |
| ‘ | Комментарий общего назначения. Используется для любых пометок, не требующих особого внимания |
| ‘. | Спорный фрагмент программу. Особенно полезен при работе в составе группы, а также при отладке чужих программ. Обозначает код, который может оказаться спорным или избыточным, или же потребовать вашего внимания позднее |
| ‘. | Код требует особого внимания! Комментарий напоминает об этом программисту. Может использоваться для кода, который необходимо тщательно проверить, удалить или восстановить в прежнем виде |
Наиболее распространенная форма комментария — обычный апостроф. Каждый раз, когда апостроф встречается в тексте программы вне строковых констант, весь текст справа от него считается комментарием. Как вы вскоре убедитесь, это позволяет разработать достаточно гибкую и универсальную систему комментирования.
В простейшем случае апостроф является единственным символом в строке и помогает визуально разделить фрагменты программы или комментария. Такие «вырожденные» комментарии неоднократно встречаются в предыдущих примерах этого урока. Как показано в приведенной таблице, за апострофом могут следовать дополнительные символы, которые используются для нестандартных комментариев.
Комментарии второго и третьего типа (см. таблицу) можно легко расширить для работы в группах. Например, в них можно включить свои инициалы, чтобы при необходимости вы могли легко найти интересующий вас код. Если некоторый фрагмент должен быть исключен из окончательного варианта программы, его можно снабдить комментарием типа
‘. «- СБ Удалить, если построение пройдет успешно.
Чтобы найти весь код, который необходимо удалить перед окончательной компиляцией, достаточно выполнить в проекте поиск строки. — СБ.
Хотя описанные приемы приносят несомненную пользу, они, конечно, не исчерпывают всех возможностей комментирования. Используйте ту методику, которая покажется вам наиболее удобной. Тем не менее, обязательно соблюдайте единый стиль комментирования — это сэкономит время отладки приложения!
Соглашения об именах
При выборе имен компонентов следует руководствоваться единым набором правил, которые называются соглашениями об именах. Эти соглашения делают исходные тексты ваших программ более понятным и наглядным. Некоторые соглашения об именах были описаны в уроке 3.
Как вы уже знаете, каждый компонент в проекте Visual Basic должен иметь уникальное имя. Visual Basic автоматически присваивает имена компонентам, включаемым в проект. Например, первой форме проекта по умолчанию присваивается имя Form1. Если оставить свойству Name это значение и включить в проект другую форму, Visual Basic автоматически присвоит ей имя Form2.
Следующей форме будет присвоено имя Form3 и т. д. Имена элементов назначаются аналогичным образом. Автоматическое назначение имен может показаться удобным, но представьте себе форму с двенадцатью кнопками, которые носят имена от Command1 до Command12. Конечно, это не помешает нормальной работе программы, но во время написания кода вам будет трудно вспомнить, что делает та или иная кнопка.
ПОДСКАЗКА Первое, что следует сделать при включении нового компонента в проект, — задать его свойству Name какое-нибудь содержательное значение. Ваша программа станет более понятной, а это ускорит процесс разработки и отладки.
Приведу лишь некоторые рекомендации, которые можно учитывать при разработке ваших собственных соглашений об именах:
О Имена переменных могут содержать символы верхнего и нижнего регистра, но без пробелов (например, UserName).
О Имена констант должны содержать символы только верхнего регистра, а вместо пробелов должны использоваться символы подчеркивания (например, ACCESS_ LEVEL_ADMIN).
В следующей таблице перечислены префиксы, используемые для самых распространенных управляющих элементов Visual Basic.
| Элемент | Префикс | Пример |
| Форма | frm | frmMain |
| Кнопка | cmd | cmdOK, cmdCancel |
| Надпись | lbl | IblName |
| Текстовое поле | txt | txtLastName |
| Комбинированное поле | cbo | cboAccounts |
| Список | 1st | IstGroups |
| Рамка | fra | fra0ptions |
| Переключатель | opt | opt0n, opt0ff |
| Флажок | chk | chkTaxDeductible |
| Графическое поле | pic | picWaterMark |
| Рисунок | img | imgSplasGraphic |
| Полоса прокрутки | scr | scrVolume |
| Таймер | tmr | tmrCountDown |
| Список устройств | drv | drvDisk |
| Список каталогов | dir | dirDirectories |
| Список файлов | fil | filHiddenFiles |
| Линия | lin | linSeparator |
| Фигура | sha | shaCircle |
| Элемент данных | dat | datLogDatabase |
| Элемент OLE | pie | oleWordDocument |
| Дерево | tvw | tvwGroups |
| Табличный список | lvw | IvwUsers |
| Список изображений | iml | imlGroups, imlUsers |
| Строка состояния | sts | stsAccountStatus |
Если вы будете работать с другими элементами, используйте рекомендованный префикс или придумайте свой вариант, похожий на перечисленные в таблице.
Понравилась статья? Добавь ее в закладку (CTRL+D) и не забудь поделиться с друзьями:
Источник: studopedia.ru