html как комментировать код
Как закомментировать на время код HTML, CSS или PHP, JS
…сегодня мы в этой коротенькой, но полезной статье, разберемся, как же комментируется различный программный код. Много говорить не стану, ибо если вас подобное заинтересовало, то вы уже столкнулись с вопросами этой задачи, и представление о ней имеете.
(в финале статьи подробное видео о правилах и способах комментирования кодов)
Но обратите внимание, что комментарии используются также и в html и php… А ведь большинство начинающих путаются на начальном этапе своей работе с сайтом и не знают, как дописать себе необходимые пояснения. Ведь бывает же так, например, вам потребуется на какое-то время деактивировать код html, а потом снова возобновить его функцию — это запросто реализовать, если вы сделали себе пометки на «полях», да мало ли что.
Но что следует помнить о «комментариях» вообще — тут всё в строгой зависимости от того, с каким файлом вы работаете конкретно, а следовательно и код применения различен.
ошибки в комментариях к коду — по версиям php
php 8
время от времени языки программирования меняются (их версии), а следовательно относитесь внимательнее к тому, что и как комментируете!
Как известно, не так давно вышла версия php 8 — некоторые пользователи столкнулись с проблемами!
В данной статье коснемся, скажем так, синтаксиса — правописания))…
Например, если комментируете в самом финале кода, то обязательно соответственно закрывайте комментарий! иначе, в новейших версиях php (подобные правила касаются многих ЯПов) бесконечно закомментированный блок вызовет ошибки! Белый экран.
…далее: никогда не ЛЕПИТЕ друг к дружке символы комментариев к тегам кода. неряшество в коде, как и в жизни, вызывает неприличные ошибки.
На мой взгляд, лучше потратить несколько лишних минут времени, но написать чистенький и аккуратный код и комментарии. Это в будущем сэкономит массу времени!
HTML Комментарии
Теги комментариев используются для вставки комментариев в исходный HTML код.
HTML Теги комментариев
Вы можете добавлять комментарии на своей HTML странице, используя следующий синтаксис:
Примечание: Комментарии не отображаются в браузере, но могут помочь документировать исходный код HTML.
С комментариями вы можете размещать уведомления и напоминания в своем HTML:
Пример
Комментарии также отлично подходят для отладки HTML, потому что вы можете закомментировать строки кода HTML, по одной, для поиска ошибок:
Пример
HTML Упражнения
Вопросы для самоконтроля
ПАЛИТРА ЦВЕТОВ
ПРИСОЕДИНЯЙТЕСЬ!
Получите ваш
Сертификат сегодня!
Связь с админом
Если вы хотите сообщить об ошибке, а также внести предложение о работе сайта, добавить объявление или рекламу на сайт, не стесняйтесь отправить админу электронное письмо на email:
Топ Учебники
Топ Справочники
Топ Примеры
Веб Сертификаты
Этот сайт оптимизирован для обучения и тестирования. Примеры могут быть упрощены для улучшения чтения и базового понимания. Учебные пособия, ссылки и примеры постоянно пересматриваются, чтобы избежать ошибок, но мы не можем гарантировать полную правильность и работоспособность всего контента. Используя этот сайт, вы соглашаетесь с тем, что прочитали и приняли условия использования, cookie и политику конфиденциальности.
Также вы можете абсолютно бесплатно скачать офлайн версию сайта W3Schools на русском архивом с GitHub и пользоваться локально на своём компьютере.
Также доступна версия сайта W3Schools на украинском языке.
Copyright 1999-2021 by Refsnes Data. All Rights Reserved.
Сайт работает на фреймворке W3.CSS.
SITE BLOGGER
создание, продвижение сайтов
Комментарии в HTML, CSS, PHP
В данном уроке я расскажу о том, как делаются комментарии в HTML, CSS, PHP. Комментарии представляют собой текст, который не виден на веб-странице. Они используется для разного рода пояснений, напоминаний, описаний для вебмастеров, что позволяет структурировать документ. Комментарии незаменимы при отладке кода, позволяют быстро сориентироваться в разметке веб-страницы и найти нужный блок. Часто комментарии применяются для отладки кода HTML. К примеру, можно временно закомментировать конкретный блок кода, чтобы он не исполнялся, а в случае необходимости легко его восстановить.
Комментарии в HTML
Комментарии в CSS
Комментарии в CSS создаются с помощью символов: /* и */. Для создания комментария нужно просто поместить код-веб страницы между этими символами:
Комментарии в PHP
Комментарии в PHP могут быть однострочными и многострочными:
1) Однострочные комментарии в PHP создаются с помощью символов: //. Достаточно просто поставить этот символ перед строкой и она будет закомментирована.Такой вариант применятся в том случае, когда комментарий состоит только их одной строки.
2) Для реализации многострочных комментариев используются символы: /* и */. Такой вариант полезен, если комментарий занимает несколько строк.
Таким образом, мы научились делать комментарии в HTML, CSS, PHP. Благодаря комментариям мы всегда можем оперативно находить нужные блоки HTML кода и, при необходимости, изменять их структуру.
Зачем комментировать исходный код и как это делать правильно
Как не забыть о том, что вы имели ввиду полгода назад, когда писали этот программный код? Разбираемся с использованием комментариев.
Комментарии — поясняющие строки в программном коде, которые позволяют понять смысл написанного. Они пишутся для людей, но игнорируются компиляторами и интерпретаторами.
Знакомый, наверно, каждому пример со словами на русском или английском языке после двух слешей — так обычно выглядят комментарии:
Программист, консультант, специалист по документированию. Легко и доступно рассказывает о сложных вещах в программировании и дизайне.
Чем комментарии могут помочь программисту
Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:
Как комментарии оформляют в коде
Комментарии бывают совсем короткими, длиной не более строки, и большими, многострочными.
Однострочные выделяют одиночным символом в начале и продолжают до конца строки, а многострочные могут иметь любую длину, но поддерживаются не всеми языками. Их отмечают специальными символами в начале и конце текста, например, /* и */.
Для выделения комментариев в коде используют разные символы:
Правила, которых принято придерживаться
У разработчиков принято использовать при комментировании несколько простых правил. Так легче работать — больше пользы и не нужно плодить лишние строки кода.
1. Комментарии помещаются прямо над кодом, к которому они относятся. Так проще понять, о чём речь, не вникая в содержание каждой строчки. Совсем короткие пояснения можно писать справа.
2. Комментируют все основные элементы кода: модули, функции, константы, глобальные переменные, интерфейсы, классы и их составные элементы (методы, свойства, константы).
3. Пишут коротко и по делу. Комментарии без смысловой нагрузки страшно раздражают. Не нужно писать комментарии типа «это гениальный код», «таблица1», «! №; %:? *» и подобные.
4. Нельзя, чтобы комментарии оскорбляли кого-то или содержали слова, которые не поймёт технарь. В поддержку движения Black Lives Matter Twitter в своем коде решил не использовать слова slave, master и blacklist. Кто-то из россиян, возможно, улыбнётся, но стандарт есть стандарт.
Документирующие и поясняющие комментарии
В зависимости от того, для чего нужны комментарии, их условно делят на два вида:
Пример на языке Java:
Из такого комментария сразу ясно, что делает программа. Не нужно вникать в исходный текст и изучать техническую документацию. Это особенно важно, если вы работаете в команде и хотите сэкономить время коллег.
Комментарии-описания иногда мешают разработчикам и отвлекают внимание от основного кода. Поэтому в большинстве современных редакторов есть возможность свернуть или скрыть комментарии.
Как комментируют функции и библиотеки
В комментариях к файлам и библиотекам указывают информацию о проекте, назначении модуля, заносят в них имя разработчика, номер версии продукта и лицензию на программное обеспечение.
Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:
Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:
Пример из той же библиотеки Lodash:
Главное здесь — избегать бессмысленных комментариев. Вот пример плохого описания процедуры на языке 1С:
К прикладным процедурам, функциям и классам делайте информативные и понятные заголовки с описанием всех входных и выходных параметров.
Как автоматизировать создание комментариев
В различных IDE есть возможность автоматизировать создание комментариев. Это делается с использованием тегов — дескрипторов, которые начинаются с символа @. Вот самые популярные:
Из таких комментариев автоматически формируется документация программы. Для этого используют генераторы документации, например, javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++, Epydoc для Pithon и другие.
Принцип работы прост. Генератор обрабатывает файл с исходным текстом, находит там имена классов, их членов, свойств, методов, процедур и функций, а затем связывает их с данными из наших комментариев с тегами. Из этой информации формируется документация в формате HTML, PDF, RTF или других.
При разработке библиотек и фреймворков обычно создается документация для API. Со временем она устаревает — в неё не успевают или просто забывают вносить изменения.
Если данные об изменениях в коде отражены в комментариях, с помощью генераторов документацию можно регулярно обновлять.
Когда нужны пояснения в коде, а когда — нет
Бывает, что одних документирующих комментариев недостаточно и нужно добавить пояснения внутри процедур или функций. Такие комментарии облегчают понимание кода — рассказывают, почему автор программы сделал что-то так, а не иначе.
Но иногда эти пояснения только ухудшают наглядность кода, бывают бессмысленны и даже вредны. Например, совершенно не нужны комментарии, просто пересказывающие действия программы:
Если вы вставили промежуточные комментарии для отладки или объяснения результатов, после окончания работы их нужно убрать. Иначе они будут захламлять код.
Например, функция вычисляет окончательную сумму, прибавляя проценты к основной. Для проверки программист вывел на экран промежуточный результат, а после закомментировал ненужный фрагмент.
После отладки их лучше удалить, оставив строки:
Простой код, без многочисленных циклов, ветвлений и переходов, пишут и структурируют так, чтобы никаких дополнительных пояснений к нему не требовалось.
Но бывают исключения. Допустим, разработчик попробовал несколько вариантов решения и выбрал один, не самый очевидный. Потом забыл ход своих мыслей, открыл код и решил использовать «более правильный и оптимальный вариант». И тут он понимает, что новое решение хуже старого; более того, раньше он уже это пробовал делать. Приходится откатывать всё назад. Чтобы не попасть в такую ситуацию, пишите поясняющие комментарии.
Пример на языке JavaScript:
Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).
Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:
Это неудачный комментарий: непонятно, зачем количество умножать на 2.
Правильно будет так:
В любом случае, старайтесь писать поясняющие комментарии как можно реже.
Комментарии в сложном коде и рефакторинг
В сложной и запутанной программе не обойтись без поясняющих комментариев. Но иногда лучше упростить сам код: разбить на отдельные функции, уменьшить размеры элементов, упростить циклы и так далее. А самим функциям, константам и переменным дать «говорящие» имена, объясняющие их назначение.
Например, есть метод, который сравнивает числа a и b. Если a > b, он возвращает true, a если a
Весь этот громоздкий кусок кода можно значительно упростить, просто убрав блок if-else:
Теперь метод выглядит намного проще и элегантнее, хотя его суть не изменилась. Подобные преобразования называются рефакторингом.
Рефакторинг меняет структуру кода, оставляя неизменной его суть. Он повышает читаемость кода и облегчает процесс его доработки. Рефакторинг не заменяет комментирование, но с ним комментариев нужно намного меньше.
Что в итоге
Комментарии — отличная штука. Они помогают команде разработчиков работать над общим проектом. А если программист один, позволят ему даже через много лет вспомнить ход своих мыслей. Но комментариев должно быть мало, иначе они превратятся во флуд.
Комментировать нужно основные элементы кода, неочевидные решения, сложные бизнес-процессы, тонкости решений и тому подобное. Не пишите комментарии, объясняющие, что и как делает процедура или функция, — это бессмысленно.
И помните, что комментарий — не панацея, он не спасёт плохой код, даже если сделает его понятнее. Сложные и запутанные фрагменты сокращайте и делайте рефакторинг, а комментируйте по минимуму.
Научиться использовать комментарии, верно документировать исходный код, писать его понятным для коллег и читабельным даже через много лет вы можете на наших курсах по программированию. Выбирайте любой и становитесь профессионалом.
Лучшие практики написания комментариев к коду
Известный профессор МТИ Гарольд Абельсон сказал: «Программы нужно писать для того, чтобы их читали люди, и лишь случайно — чтобы их исполняли машины». Хотя он намеренно преуменьшил важность исполнения кода, однако подчёркивает, что у программ две важные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и с одинаковой лёгкостью воспринимают все синтаксически корректные программы. У людей всё иначе. Одни программы нам воспринимать легче, чем другие, и мы ищем комментарии, которые помогут нам разобраться.
Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.
Как писал Питер Фогель:
Первое правило: комментарии не должны дублировать код
Многие начинающие программисты пишут слишком много комментариев, потому что их к этому приучили. Я видел, как старшекурсники на факультете информатики добавляют комментарии к каждой закрывающей скобке, чтобы показать закрытие блока:
Я слышал о преподавателях, которые требуют от студентов комментировать каждую строку кода. Для совсем новичков это может быть оправдано, однако такие комментарии как боковые колёсики на детском велосипеде, которые по мере роста надо снять.
Неинформативные комментарии вредны, потому что:
Комментарий не добавляет полезной информации и требует усилий по поддержке.
Требования комментировать каждую строку справедливо высмеяли на Reddit:
Второе правило: хорошие комментарии не оправдывают непонятный код
Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:
Комментарий был бы не нужен, если дать переменной правильное название:
Как написали Керниган и Плогер в книге «The Elements of Programming Style»: «Не комментируйте плохой код, а переписывайте его».
Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде
Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:
Отладка вдвое труднее первоначального написания кода. Поэтому если вы пишете код как можно умнее, то вы по определению не настолько умны, чтобы его отладить.
Предупреждение читателям, чтобы они держались подальше от вашего кода, сродни включению аварийных огней: признание в том, что вы делаете что-то незаконное. Лучше перепишите код так, чтобы вы сами понимали его достаточно, чтобы объяснить другим. Или ещё лучше, чтобы его вообще не требовалось объяснять.
Четвёртое правило: комментарии должны исключать путаницу, а не вносить её
Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:
[Питер Самсон] особенно усложнял ситуацию тем, что отказывался добавлять в свой исходный код комментарии с пояснением, что он делает в каждом конкретном случае. Одна из распространённых программ, написанных Самсоном, состояла из сотен инструкций на ассемблере с единственным комментарием после инструкции под номером 1750. Комментарий был такой: RIPJSB, и люди ломали головы над тем, что это означает, пока кто-то не догадался, что в 1750-м году умер Бах, и что Самсон написал аббревиатуру фразы “Rest In Peace Johann Sebastian Bach”.
Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.
Пятое правило: объясняйте в комментариях не идиоматический код
Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):
Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:
Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.
Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.
Если вы такой же, как и большинство программистов, то иногда вы используете найденный в сети код. Добавляйте ссылку на исходник, чтобы будущие читатели имели полный контекст, например:
Если перейти по ссылке, то вы обнаружите, что:
Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.
Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.
Вы также можете ссылаться на оказавшиеся полезными руководства в качестве благодарности их авторам и ради экономии времени читателей:
Седьмое правило: добавляйте ссылки на внешние примеры в тех случаях, когда это полезнее всего
Конечно, не все ссылки ведут на Stack Overflow.
Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.
Восьмое правило: исправляя баги, добавляйте комментарии
Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:
Комментарий не только помогает понять код в конкретных методах, но и определить, нужен ли ещё этот код и как его тестировать. Также комментарий может ссылаться на систему отслеживания ошибок:
Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).
Девятое правило: помечайте комментариями незаконченные реализации
Иногда необходимо проверять код, даже несмотря на его ограничения. Хотя может быть заманчиво не рассказывать о недостатках своего кода, лучше сделать это явно, например, в комментарии TODO:
Стандартный формат для таких комментариев помогает оценить и адресовать технический долг. Ещё лучше, если добавите задачу в систему отслеживания ошибок и вставите ссылку в комментарий.