Html комментарии в коде и их польза для веб-мастеров
Автор Дмитрий Костин На чтение 3 мин. Опубликовано
Доброго всем времени суток, мои дорогие друзья. Я очень рад вас видеть на страницах моего блога, и я надеюсь вам также интересно здесь присутствовать. По крайней мере я стараюсь, чтобы это было именно так. И сегодня у меня для вас простенькая тема по сайтостроению, применение которой никак не повлияет на сам сайт, но зато сможет облегчить вам и другим пользователям «ковыряние в коде».
Речь сегодня пойдет про html комментарии в коде. Эта вещь очень классная. И хоть она и не обязательная, я всё равно призываю вас этими штуками пользоваться. Ни для кого не секрет, что дизайн и верстку для своего блога я заказывал у отдельных людей: Юли и Андрея.
Так вот, иногда я хочу что-либо подправить в коде, и чтобы лишний раз не дергать верстальщика по пустякам, я сам иду в редактор и правлю код сам (ежели это в моих силах). И комментарии, которые оставил Андрей в коде, значительно облегчают данный процесс. Кроме того комментарии помогают, если вы сделали свою работу и ушли. Тогда другой человек сможет быстрее разобраться в вашем коде.
Ну а теперь давайте на живом примере посмотрим, как их делать:
- Давайте зайдем в любой html-документ, где у нас есть какое-либо содержимое.
- Теперь перед любой записью поставьте <!— и напишите после него сам комментарий, например «Заголовок».
- После этого поставьте закрывающий тег комментариев —>, иначе все содержимое страницы станет одним большим комментарием)).
На деле это выглядит так:
Ну а теперь, если мы сохраним документ и откроем его в браузере, то что мы увидим? А ничего мы не увидим. Вернее не увидим мы никаких изменений, так как всё, что находится внутри <!— —> автоматически становится невидимым для браузера.
И кстати сейчас я вам расскажу про очень актуальное использование этих тегов на своем же примере. Когда верстальщик сделал мне сайт, то в правом сайдбаре по условиям дизайна были расположены два баннера, точнее специальные места для них. Я пока не собираюсь ставить никакие баннеры, поэтому решил убрать их на время, чтобы глаза не мозолили.
Удалять их из кода я естественно не собирался, но как же их тогда убрать? Можно конечно скопировать данный код или скрипт в отдельный документ, а с сайта всё убрать. Но есть способ лучше. Я просто загнал все эти коды в комментарии.
Таким образом я ничего не удалил, а просто на время скрыл. Как раз недавно я сделал баннер для своего конкурса на блоге. И вот я зашел в код, поставил баннер, прописал путь в коде и убрал теги комментариев. Как видите, все прекрасно работает.
В общем суть вы поняли, я надеюсь. Если что-то надо скрыть не удаляя, то лучше всего заключить всё в комментарии.
Ну а на этом я свою сегодняшнюю статью заканчиваю. Как вам? Была ли информация полезной? Если да, то обязательно подпишитесь на обновления статей моего блога. Также для полного изучения верстки сайтов на HTML и CSS я рекомендую вам посмотреть отличный курс по этой теме. Курс — просто бомба, и рассказано всё великолепно, буквально разжевано.
Ну а с вами я на сегодня прощаюсь. Обязательно заходите еще на мой блог, чтобы не пропустить интересную для вас информацию. Ну а вам я желаю успехов во всех ваших начинаниях. Увидимся в других моих статьях. Пока-пока!
С уважением, Дмитрий Костин.
Комментарии в коде — полезные, бессмысленные, вредные? / Habr
Как-то проглядывая код некоторых старых модулей, вновь подумал о роли комментариев. Вопрос хоть и тривиальный и обсужденный миллионы раз в книгах, блогах, статьях и форумах, а все-таки подчас задевает за живое. При этом, о пользе комментариев пишут гораздо чаще, чем о их вреде.Поэтому я выскажу несколько немного провокационных утверждений, затем попробую подкрепить их примерами. Посмотрим что получится. Написанное относится как к (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:
По просьбам в комментах, даю ссылку на пару книг, которые полезно прочитать любому программисту, чтобы не писать таких комментариев (и не делать многих других ошибок)
Стив МакКоннелл. Совершенный код. www.ozon.ru/context/detail/id/5508646
Мартин Фаулер. Рефакторинг. Улучшение существующего кода. www.ozon.ru/context/detail/id/4952415
Тег — комментарий
Поддержка браузерами
Описание
<!-- --> используется для добавления комментариев в исходный код документа. Все содержимое, которое располагается между символами <!-- и -->, не отображается в окне браузера.HTML комментарий может содержать внутри себя другие HTML теги, если на время надо прекратить их работу, кроме тега комментария. Вложенные комментарии (один комментарий в другом) не поддерживаются. Если, при отключении больших частей исходного кода, всё-таки один комментарий оказался внутри другого, то внешний комментарий будет закрыт символами --> внутреннего комментария. В этом случае всё, что располагается после этих символов, будет расценено браузером как обычная разметка документа и выведено на страницу.
Если комментарий расположен внутри тега <title>, он трактуется как текст и будет показан в заголовке страницы. Проще говоря, тег <!-- --> внутри тега <title>
Примечание: html комментарии в коде являются многострочными, то есть если вы открыли комментарий с помощью символов <!-- и забыли его закрыть символами -->, то всё что находится после <!-- будет расцениваться браузером как комментарий.
Комментарии в основном используют, чтобы сопроводить код описанием, оставить какое-нибудь напоминание — это существенно помогает при просмотре и редактировании кода в будущем. Так же комментарии позволяют структурировать документ, добавляя описание к определенным блокам кода.
Атрибуты
нет
Пример
<!--Это комментарий. Комментарии не отображаются в окне браузера--> <!--горизонтальная линия--> <hr>
Результат данного примера в окне браузера:
Как оформлять комментарии в html, css, php коде|Всё гениальное просто
Для чего нужны комментарии в исходном коде программ
Опытные программисты считают, что комментарии должны описывать не сам код, а намерения человека, который его пишет. Это мнение обусловлено тем, что незачем дублировать на человеческом языке то, что написано на машинном. Вместо этого программисту нужно стремиться делать понятным и простым сам код: следовать общепринятым правилам, а также давать переменным, классам, функциям и т.д. наиболее подходящие имена. Поэтому объяснять в комментариях нужно только не очень очевидные нюансы, которые, например, невозможно понять без глубокого изучения достаточно большого объема кода. Комментарии в исходном коде программы нередко используются для того, чтобы исключить какую-то часть инструкций. В частности, такой метод применяется при дебагинге или оптимизации программ.Как оформлять комментарии на разных в HTML, CSS и PHP коде
Многие языки программирования имеют сходство друг с другом, но вместе с этим у каждого из них имеются свои особенности. Это касается не только названий операторов и стиля их расположения в коде, но и особенностей написания комментариев.Как писать комментарии в HTML-коде
Создать комментарий внутри HTML – очень легко. За это в данном языке разметки отвечает тег . Вместо «blah-b…» может быть написано абсолютно все, что угодно на любом языке (но лучше, конечно, использовать английский – так принято в программировании). Очень важный нюанс: двойной дефис («—«) внутри HTML-комментария воспринимается любым браузером, как завершение «». Это, в свою очередь, приводит к ошибке (в случае с HTML – выводу фрагмента комментария). Поэтому при создании разметки страниц следует избегать такого вида текста: «». Вместо этого лучше написать «».