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

7 ответов

Решение

Ничего такого. Некоторые разработчики делают это для отставания старого кода. Это плохая практика, так как вместо этого следует использовать контроль исходного кода (например, SVN или GIT), и вся история будет там вместе с сообщениями о коммитах, почему они были закомментированы / заменены.

Их определенно безопасно удалить, но вы можете спросить разработчика, почему они его закомментировали, вместо того, чтобы просто удалить их.

2

2013-01-07 12:26

Удаление блока комментария, такого как выше, не окажет влияния на вывод кода.

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

2013-01-07 12:25

Не трогайте, пока не узнаете, почему код прокомментирован. Спросите разработчика, который разработал этот код, или просмотрите код и сначала поймите, нужны ли вам эти строки или нет.

2013-01-07 12:26

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

Да, совершенно безопасно удалить эти комментарии, если они вас беспокоят.

2013-01-07 12:25

Вы единственный, кто действительно знает, можно ли безопасно удалить линии.

В принципе, да — если ваше приложение работает как задумано, обязательно удалите их.

2013-01-07 12:25

Это безопасно удалить их. На самом деле нет смысла иметь такие комментарии, если вы используете систему контроля версий. Этот вид комментариев обычно возникает, когда люди не используют систему управления версиями и комментируют код, чтобы попробовать что-то и хотят сохранить старый код, на всякий случай. Если вы используете систему контроля версий, вы всегда можете вернуть старую версию кода, поэтому обязательно удалите эти комментарии. Если вы не используете систему контроля версий, вы действительно должны.

2013-01-07 12:26

Да, эти строки можно безопасно удалить. Вы должны быть осторожны, однако, что код все еще не актуален; это могло быть оставлено там по причине другим разработчиком.

Комментарии часто используются в качестве инструмента для «отключения» части кода, не удаляя ее полностью, так что если вам понадобится код позже, вы можете просто раскомментировать его, чтобы восстановить.

Однако не рекомендуется оставлять закомментированный код в долгосрочной перспективе (для этого нужен контроль версий).

2013-01-07 12:25

Новый ответ

Вы легко справляетесь, так как в вашем коде нет ни строк PHP, ни комментариев. Это означает, что комментирование этого фрагмента кода так же просто, как:

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

Вы не можете вставлять это в один комментарий, так как он сломается в строке 7.

Вместо этого вы можете использовать для встраивания кода в строку и никогда не использовать эту строку:

Несколько замечаний:

• Почему я использую NOWDOC вместо простой строки?

  Простая строка будет разбита на строку 5 (на «Says» hello «). Строка с одним кадром будет разбита на строку 2 (на» Вы»).

• Почему я использую NOWDOC вместо HEREDOC?

  Потому что я не хочу, чтобы имена переменных обрабатывались. Переменные переменных в таком контексте могут вызвать проблемы, которые очень трудно найти и отладить, поскольку область изменений изменяется.

• Что это за страшный GUID2328…?

  Я использую GUID, чтобы убедиться, что, во-первых, строка никогда не завершится до фактического конца, и, во-вторых, строковая переменная никогда не будет разумно использоваться позже в коде. Я поместил префикс GUID, так как HEREDOC/NOWDOC требует, чтобы имя начиналось буквой, а не цифрой.

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

• Это повлияет на производительность веб-приложения, верно?

  Не используйте преждевременную оптимизацию. Инициализация строки может иметь стоимость исполнения, но либо она будет достаточно мала для ухода, либо даже PHP-интерпретатор будет достаточно умным, чтобы оптимизировать код и удалить неиспользуемую строку (я очень сомневаюсь в этом).

Обратите внимание, что вы не должны комментировать большие куски кода в первую очередь. Если вам не нужен код, просто удалите его

Если вы считаете, что вам понадобится это позже, пусть контроль версий позаботится об этом (вы используете контроль версий, не так ли?).

Когда нужны пояснения в коде, а когда — нет

Бывает, что одних документирующих комментариев недостаточно и нужно добавить пояснения внутри процедур или функций. Такие комментарии облегчают понимание кода — рассказывают, почему автор программы сделал что-то так, а не иначе.

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

Если вы вставили промежуточные комментарии для отладки или объяснения результатов, после окончания работы их нужно убрать. Иначе они будут захламлять код.

Например, функция вычисляет окончательную сумму, прибавляя проценты к основной. Для проверки программист вывел на экран промежуточный результат, а после закомментировал ненужный фрагмент.

После отладки их лучше удалить, оставив строки:

Простой код, без многочисленных циклов, ветвлений и переходов, пишут и структурируют так, чтобы никаких дополнительных пояснений к нему не требовалось.

Но бывают исключения. Допустим, разработчик попробовал несколько вариантов решения и выбрал один, не самый очевидный. Потом забыл ход своих мыслей, открыл код и решил использовать «более правильный и оптимальный вариант». И тут он понимает, что новое решение хуже старого; более того, раньше он уже это пробовал делать. Приходится откатывать всё назад. Чтобы не попасть в такую ситуацию, пишите поясняющие комментарии.

Пример на языке JavaScript:

Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).

Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:

Это неудачный комментарий: непонятно, зачем количество умножать на 2.

Правильно будет так:

Чем комментарии могут помочь программисту

Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:

Помогают быстрее разобраться в коде — если появилась ошибка или нужно что-то изменить d программе

Это важно и разработчику, и тем, кто будет заниматься кодом после него.
Не дают запутаться в логике — при создании новых библиотек, процедур, функций и системных переменных.
Объясняют результаты работы — при отладке или проверке программы. Это понимание необходимо тестировщикам из отдела QA.
Описывают сложные алгоритмы и формулы — в математических, физических или экономических расчётах и других сложных вычислениях

Это позволяет разобраться в готовом коде тем, у кого нет глубоких знаний в какой-то предметной области.

Правильное использование комментариев

Обычно комментарии используются для трех вещей. Во-первых, для заданной библиотеки, программы или функции комментарии лучше всего использовать для описания того, что делает библиотека, программа или функция. Обычно они размещаются в верхней части файла или библиотеки или непосредственно перед функцией. Например:

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

Это особенно важно при работе в команде, где не все знакомы со всем кодом

Во-вторых, внутри библиотеки, программы или функции, описанной выше, можно использовать комментарии, чтобы описать, как код будет достигать своей цели.

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

В-третьих, на уровне инструкций следует использовать комментарии, чтобы описать, почему код что-то делает. Комментарий плохой инструкции объясняет, что делает код. Если вы когда-нибудь напишете настолько сложный код, который требует комментария, чтобы объяснить, что делает инструкция, вам, вероятно, лучше переписать свою инструкцию, а не комментировать ее.

Вот несколько примеров плохих комментариев к строке и хороших комментариев к инструкции.

Плохой комментарий:

Причина: мы уже видим, что прицел (sight) устанавливается на 0, посмотрев на инструкцию.

Хороший комментарий:

Причина: теперь мы знаем, почему прицел игрока установлен на 0.

Плохой комментарий:

Причина: мы видим, что это расчет стоимости, но почему количество умножается на 2?

Хороший комментарий:

Причина: Теперь мы знаем, почему эта формула имеет смысл.

Программистам часто приходится выбирать между решением задачи одним или другим способом. Комментарии – отличный способ напомнить себе (или рассказать кому-то другому), почему вы приняли одно решение вместо другого.

Хорошие комментарии:

Наконец, комментарии должны быть написаны таким образом, чтобы иметь смысл для тех, кто не знает, что делает код. Часто программист говорит: «Совершенно очевидно, что он делает! Я ни за что не забуду об этом,». Угадайте, что? Это не очевидно, и вы удивитесь, как быстро вы забудете. 🙂 Вы (или кто-то другой) поблагодарите вас позже за то, что вы написали, что, как и почему делается в вашем коде на человеческом языке. Читать отдельные строки кода легко. Понимание того, для чего они предназначены, – нет.

Лучшая практика

Обильно комментируйте свой код и пишите свои комментарии, как если бы разговаривали с кем-то, кто не знает, что делает код. Не думайте, что вы вспомните, почему вы сделали конкретный выбор.

Примечание автора

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

🙂 Читая остальные руководства, имейте в виду, что комментарии служат намеренно образовательной цели, а не пытаются продемонстрировать, как выглядят хорошие комментарии.

11 ответов

Решение

Зависит от расширения. Если это.html, вы можете использовать начать и закончить комментарий. Это действительно единственная альтернатива, о которой я могу думать. http://jsfiddle.net/SuEAW/

9

2010-09-21 03:18

Да, чтобы закомментировать структурные метаданные,

Закомментируйте большие разделы HTML (Блок комментария)

мой личный путь в .html файле открывается: и закройте его

Это обходной путь к проблеме, так как это не HTML.

Учитывая ваш код в.html…

И в случае HTML внутри PHP- файла, используя тег комментария или же и закройте его , Помните, что файл должен иметь расширение.php и не работать в формате.html.

Учитывая ваш код в.php…

Ничего не стоит, кроме HTML, но обычная практика разработчиков — закомментировать части метаданных, чтобы они не отображались и / или не выполнялись в браузере. В HTML комментирование нескольких строк может занимать много времени. Полезно исключать фрагменты структурных метаданных шаблона, содержащие комментарии, CSS или код и систематическое комментирование, чтобы найти источник ошибки. Комментировать блоки считается плохой практикой, поэтому рекомендуется использовать систему контроля версий. Атрибут «тип» является обязательным в HTML4 и необязательным в HTML5.

17

2015-05-10 04:25

Вы можете попробовать заменить с другой строкой, скажем, и сделайте поиск и замените свой редактор, когда вы хотите вернуть закрывающие теги.

2

2010-09-21 03:29

Поместите пробел между «->» ваших комментариев заголовка. например, «—>»

2014-01-09 14:50

Я считаю, что это тоже проклятие комментариев в стиле XML. Есть XML-редакторы, такие как eclipse, которые могут выполнять комментирование блоков. В основном автоматически добавляются лишние в строке и удаляются их. Может быть, они целенаправленно затруднили комментировать тот стиль документа, который, как предполагалось, должен был быть самоочевидным с тегами.

2010-09-21 03:27

Мои шаблоны представлений — это, как правило, файлы.php. Это то, что я буду использовать сейчас.

Решение очень похоже на то, что предложил @Robert, работает для меня. Не очень чисто, я думаю.

-1

2010-09-21 04:00

Следующее хорошо работает в файле.php.

-1

2014-04-25 16:43

У Eclipse Juno есть хороший способ для этого. Вы просто делаете cmd+

-1

2013-04-02 19:04

Нет, если вы не найдете инструмент, который делает то, что вы описали для вас.

-2

2010-09-21 03:16

В зависимости от вашего редактора это должен быть довольно простой макрос для написания.

• Перейти к началу строки или выделенной области
• Вставить
• Перейти к концу строки или выделенной области
• Вставить ->

Еще один макрос, чтобы отменить эти шаги, и все готово.

Изменить: этот упрощенный подход не обрабатывает вложенные теги комментариев, но должен облегчить комментирование / раскомментирование в общем случае.

-3

2010-09-21 04:08

(Нож) (Ближе)

например,

-7

2014-03-22 02:34

Что такое комментарии и зачем они нужны?

Комментариями принято называть текстовые пояснения, которые улучшают понимание кода и находятся непосредственно в самой программе. Благодаря специальному синтаксису, они выделяются на фоне инструкций, предназначенных для выполнения компьютером. Это дает возможность компилятору и интерпретатору игнорировать подобные текстовые вставки, во время обработки исходного кода программы.

Поскольку комментарии никак не затрагивают результат выполнения других инструкций, их можно использовать для временного закрытия отдельных блоков кода. Это ускоряет поиск ошибок и облегчает тестирование программы.

Таким образом, комментарии представляют собой специальные текстовые строки, которые никоим образом не влияют на ход выполнения программы

При желании в них можно писать все что угодно, поскольку компилятор и интерпретатор не будут обращать на них внимание. Грамотное использование комментариев позволяет значительно улучшить понимание текста программы другими людьми во время работы над общим проектом

Кроме того, реализация подобных пояснений помогает их автору быстро разбираться в ранее написанном коде. Такая потребность часто возникает при необходимости улучшить или доработать программу.

20071113

Vim: как закоментировать блок кода

Во многих языках программирования есть синтаксис комментариев, при котором всё начиная с некоторой последовательности символа и до конца строки является комментарием. Чаще это комментирующими символами являются: « # » (скриптовые языки), « // » (C++ и компания) или « ; ». Это довольно удобно, если надо закомментировать строчку. Если же надо так закоментировать несколько подряд идущих строк, то добавление символа комментария в каждую строчку вручную довольно утомительно.

К счастью, в редакторе vim есть возможность сделать это быстро:

1. CTRL-v (для выделения блока текста движением курсора вниз (j) или вверх (k)),
2. затем заглавная I (вставка во все строки блока) и комментирующие символы, которые нужно добавить (например, « // » или « # »), ESC.

И всё, 6+N нажатий на клавиши для комментирования N строк текста

Обратите внимание, что команда блоковой вставки — это заглавная I , а не строчная, как обычно

Удалять можно также быстро: CTRL-v , выделение блока, X . Если символов комментирования два («//», «–») повторяем последнюю команду: . (точка). И всё! Никаких замен.

Пользователям vim под Windows следует использовать CTRL-Q вместо CTRL-V

Комментирование в PHP

Для PHP комментарии и правила их использования так же отличаются. Так если вам нужно закомментировать какую-то одну строку или сделать пометку в теле фрагмента кода, то вам нужно использовать двойной слэш (//). Например:

PHP

<?php
if (is_front_page() ) {
echo(‘<style>…</style>’); // действие для главной страницы
} else {
echo(‘<style>…</style>’); // действие для не главной страницы
}
?>

1 2 3 4 5 6 7

<?php if(is_front_page()){ echo(‘<style>…</style>’);// действие для главной страницы }else{ echo(‘<style>…</style>’);// действие для не главной страницы } ?>

Если же вам нужно закомментировать несколько строк, то для этого можно использовать символы для комментирования /* и */, такие-же как для css-стилей, но с одним отличием:

PHP

<?php
/* if( is_page_template( ‘page-templates/contact.php’ ) ) {
$sidebar = ‘colornews_contact_page_sidebar’;
}
else {
$sidebar = ‘colornews_right_sidebar’;
} */
?>

1 2 3 4 5 6 7 8

<?php /*  if( is_page_template( ‘page-templates/contact.php’ ) ) {             $sidebar = ‘colornews_contact_page_sidebar’;          }          else {             $sidebar = ‘colornews_right_sidebar’;          } */ ?>

Обратите внимание! Символы комментария нужно ставить внутри фрагмента PHP-кода. Если вы поставите /* перед <?php , а */ после ?>, то комментирование работать не будет.. Сегодня я вам показала все основные способы комментирования для HTML, CSS и PHP которые вы можете использовать при создании сайтов

Даже более того, я бы вам советовала выучить их и использовать как можно активнее. Так как с таким кодом, в котором строки имеют пояснения и сам код структурирован с использованием комментариев, намного проще разобраться

Сегодня я вам показала все основные способы комментирования для HTML, CSS и PHP которые вы можете использовать при создании сайтов. Даже более того, я бы вам советовала выучить их и использовать как можно активнее. Так как с таким кодом, в котором строки имеют пояснения и сам код структурирован с использованием комментариев, намного проще разобраться.

А у меня на сегодня все. До встречи в следующих статьях!

С уважением Юлия Гусарь

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

Преобразование одной или нескольких строк кода в комментарий называется закомментированием кода. Это предоставляет удобный способ (временно) исключить фрагменты вашего кода из включения в скомпилированную программу.

Чтобы закомментировать одну строку кода и временно превратить эту строку кода в комментарий, просто используйте однострочный комментарий :

Незакомментированный код:

Закомментированный код:

Чтобы закомментировать блок кода и временно превратить этот блок кода в комментарий, используйте в нескольких строках кода или многострочный комментарий .

Незакомментированный код:

Закомментированный код:

или же

Есть несколько причин, по которым вы можете захотеть это сделать:

1. Вы работаете над новым фрагментом кода, который еще не компилируется, и вам нужно запустить программу. Компилятор не позволит вам скомпилировать код, если есть ошибки компиляции. Комментирование кода, который не компилируется, позволит программе скомпилироватьсь, чтобы вы могли ее запустить. Когда вы будете готовы, вы сможете раскомментировать код и продолжить работу над ним.
2. Вы написали новый код, который компилируется, но работает некорректно, и у вас нет времени исправить его. Комментирование неработающего кода гарантирует, что он не будет выполняться и не вызовет проблемы, пока вы не исправите его.
3. Поиск источника ошибки. Если программа не дает желаемых результатов (или дает сбой), иногда может быть полезно отключить части вашего кода, чтобы посмотреть, можете ли вы определить причину, по которой она работает некорректно. Если вы закомментировали одну или несколько строк кода, и ваша программа начинает работать должным образом (или перестает давать сбой), скорее всего, то, что вы в последний раз закомментировали, было частью проблемы. Затем вы можете выяснить, почему эти строки кода вызывают проблему.
4. Вы хотите заменить один фрагмент кода другим фрагментом кода. Вместо того чтобы просто удалять исходный код, вы можете закомментировать его и оставить для справки, пока не убедитесь, что новый код работает правильно. Убедившись, что ваш новый код работает, вы можете удалить старый закомментированный код. Если вам не удается заставить новый код работать, вы всегда можете удалить новый код и раскомментировать старый код, чтобы вернуться к тому, что было раньше.

Закомментирование кода – обычное дело при разработке, поэтому многие IDE поддерживают комментирование выделенного участка кода. Доступ к этой функции зависит от IDE.

Для пользователей Visual Studio

Вы можете закомментировать или раскомментировать выделенный фрагмент с помощью меню Правка (Edit) → Дополнительно (Advanced) → Закомментировать выделенный фрагмент (Comment Selection) или Раскомментировать выделенный фрагмент (Uncomment Selection).

Для пользователей Code::Blocks

Вы можете закомментировать или раскомментировать выделенный фрагмент с помощью меню Edit (Правка) → Comment (Комментарий) или Uncomment (Раскомментировать) или Toggle comment (Переключить комментарий) или любой другой инструмент для комментирования.

Совет

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

Если вам нужно закомментировать блок кода, содержащий многострочные комментарии, вы также можете рассмотреть возможность использования директивы препроцессора , которую мы обсуждаем в уроке «2.9 – Знакомство с препроцессором».

Стандартный комментарий

В языке HTML закомментировать часть кода проще всего с помощью специальных пар символов. Перед началом комментария необходимо указать «». Таким образом, всё, что окажется внутри этой конструкции, будет скрыто для пользователя при загрузке страницы.

Стоит отметить, что при работе с комментарием необходимо быть предельно внимательным. Определяя его границы, нужно проверять, не попал ли в него какой-нибудь открывающий или закрывающий тег, вторая часть которого осталась за его пределами — в этом случае загрузка страницы будет некорректной. Также нельзя создавать внутри одного комментария ещё несколько — при таком написании первый сигнал к завершению части комментирования откроет всю последующую часть скрытого текста.

Ниже представлен пример правильно написания:

Комментируем код CSS

Таким образом вы делаете себе пояснение. Или можно вообще закомментировать этот скрипт css
так: просто оберните

Введите выбранные блоки кода

В разделе «Отображаемый код». При написании и редактировании кода в режиме просмотра кода или просмотра кода вы можете изменить уровень отступов выбранного кодового блока или строки кода, перемещая код вправо или влево на одной вкладке.

Отпустить выбранные блоки кода

Навигатор кода отображает список источников кода для определенного выбора на странице. Если вы нажмете на гиперссылку в навигаторе кода, файл с соответствующим сегментом кода будет открыт. Файл отображается в области связанных файлов, когда он активирован.

/* здесь КОД */

/*a:hover, a:focus {
color: #D5071E;
text-decoration: underline; /*ПОДЧЁРКИВАНИЕ ВНИЗУ*/
}*/

Обращаю ваше внимание на то, что — закомментировать полный цикл кода css таким способом можно, но!! тогда придётся убрать повторные комментарии /*ПОДЧЁРКИВАНИЕ ВНИЗУ*/ , или поиграть слэшами, если пояснение важно))

Иначе будет ошибка!!

Ко сведению:

Если панель «Связанные файлы» не выбрана, выбранный файл открывается как отдельный документ в окне документа. Если правило интегрировано в файл, оно отображается в режиме разделения. Навигатор кода отображает гиперссылки на код для области, на которую вы нажали.
. Вы также можете открыть навигатор кода, щелкнув соответствующий индикатор. Этот индикатор отображается рядом с точкой вставки на странице, когда мышь не перемещается в течение двух секунд.

Отключить элемент отображения для навигатора кода

• Откройте навигатор кода для нужной области на странице.
• Нажмите на соответствующий сегмент кода.

Соответствующие источники кода сгруппированы в файлы в навигаторе кода, а файлы перечислены в алфавитном порядке.

• Откройте Навигатор кода.
• В нижнем правом углу выберите Отключить индикатор.
• Нажмите кнопку за пределами навигатора кода, чтобы закрыть ее.

Затем снимите флажок, чтобы отключить индикатор. Просмотрите документ в режиме просмотра кода или просмотра кода.
. Подменю «Функции» не отображается в представлении «Дизайн».

Если открыть исходный код страницы — Ctrl+U
и взглянуть… то увидим, что закомментированный кусок кода css замечательно отображается в сгенерированном документе! это если css использовалось (задавались свойства) прямо в html

В «Инспекторе кодов» нажмите кнопку «Список всех функций» на панели инструментов. Выберите имя функции, чтобы перейти к этой функции в коде. Возможно, что экстернализация этих тегов скриптов приводит к неожиданным результатам. Тем не менее, вы можете отменить изменения в любое время в течение того же сеанса редактирования. После закрытия страницы вы не можете отменить свои изменения.
. Хороший код или плохой код — существует множество определений того, что качество кода распознается. Однако четкость кода часто является важным критерием.

К каким золотым правилам следует прикладывать разработчиков, чтобы сделать их жизнь не сложнее, чем необходимо? Никто не читает или не работает с плохим кодом. Попытка разгадать плохой код других программистов час за часом — это просто не совсем приятно, как соглашаются большинство разработчиков.

Английское наречие (слова) будут читаемы. Русская символика — нет.