Как написать комментарий в css

Второе правило: хорошие комментарии не оправдывают непонятный код

Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:

private static Node getBestChildNode(Node node) < Node n; // best child node candidate for (Node node: node.getChildren()) < // update n if the current state is better if (n == null || utility(node) >utility(n)) < n = node; >> return n; > 

Комментарий был бы не нужен, если дать переменной правильное название:

private static Node getBestChildNode(Node node) < Node bestNode; for (Node currentNode: node.getChildren()) < if (bestNode == null || utility(currentNode) >utility(bestNode)) < bestNode = currentNode; >> return bestNode; > 

Как написали Керниган и Плогер в книге "The Elements of Programming Style": «Не комментируйте плохой код, а переписывайте его».

Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде

Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:

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

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

Четвёртое правило: комментарии должны исключать путаницу, а не вносить её

Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:

[Питер Самсон] особенно усложнял ситуацию тем, что отказывался добавлять в свой исходный код комментарии с пояснением, что он делает в каждом конкретном случае. Одна из распространённых программ, написанных Самсоном, состояла из сотен инструкций на ассемблере с единственным комментарием после инструкции под номером 1750. Комментарий был такой: RIPJSB, и люди ломали головы над тем, что это означает, пока кто-то не догадался, что в 1750-м году умер Бах, и что Самсон написал аббревиатуру фразы “Rest In Peace Johann Sebastian Bach”.

Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.

Пятое правило: объясняйте в комментариях не идиоматический код

Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):

final Object value = (new JSONTokener(jsonString)).nextValue(); // Note that JSONTokener.nextValue() may return // a value equals() to null. if (value == null || value.equals(null))

Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:

if (b == true) 

Я удивился, почему бы не заменить его просто на if (b) , как сделал бы это на Java. В результате небольшого исследования я выяснил, что допускающие пустое значение булевы переменные явным образом сравниваются с true, чтобы избежать уродливой проверки на null:

if (b != null && b) 

Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.

Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.

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

• какую задачу вы решали;
• кто предоставил код;
• почему это решение рекомендовано;
• что думали об этом комментаторы;
• работает ли это ещё;
• как его можно улучшить.

/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */ 

Если перейти по ссылке, то вы обнаружите, что:

• Автора кода зовут Tomáš Procházka, он входит в топ-3% на Stack Overflow.
• Один из комментаторов предложил улучшение, уже внесённое в репозиторий.
• Другой комментатор предложил способ избежать пограничного случая.

// Magical formula taken from a stackoverflow post, reputedly related to // human vision perception. return (int) (0.3 * red + 0.59 * green + 0.11 * blue); 

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

Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.

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

// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html // for a great reference and examples. 

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

Конечно, не все ссылки ведут на Stack Overflow.

// http://tools.ietf.org/html/rfc4180 suggests that CSV lines // should be terminated by CRLF, hence the \r\n. csvStringBuilder.append("\r\n"); 

Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.

Восьмое правило: исправляя баги, добавляйте комментарии

Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:

 // NOTE: At least in Firefox 2, if the user drags outside of the browser window, // mouse-move (and even mouse-down) events will not be received until // the user drags back inside the window. A workaround for this issue // exists in the implementation for onMouseLeave(). @Override public void onMouseMove(Widget sender, int x, int y)

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

// Use the name as the title if the properties did not include one (issue #1425) 

Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).

Девятое правило: помечайте комментариями незаконченные реализации

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

// TODO(hal): We are making the decimal separator be a period, // regardless of the locale of the phone. We need to think about // how to allow comma as decimal separator, which will require // updating number parsing and other places that transform numbers // to strings, such as FormatAsDecimal 

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

Заключение

Комментарии не оправдывают и не улучшают плохой код. Они дополняют хороший код, предоставляя другой тип информации. Как писал Джефф Этвуд, один из сооснователей Stack Overflow: «Код говорит вам «как», а комментарии говорят «почему»». Следование описанным правилам сэкономит время и нервы вам и вашей команде.

• лучшие практики
• комментирование кода
• никто не читает теги

• Блог компании VK
• Программирование
• Анализ и проектирование систем
• Проектирование и рефакторинг

Тег HTML комментарий

Тег используется для написания комментария в коде HTML документа.

HTML комментарии призваны улучшить читабельность кода. В комментариях обычно указывается объяснение участка кода, что упрощает процесс редактирования HTML страницы в дальнейшем.

Комментарии в HTML не отображаются на странице в браузере пользователю, однако их можно увидеть в исходном коде веб-страницы (см. пример ниже).

Синтаксис

Отображение в браузере

На картинке ниже показано отображение HTML комментариев в коде страницы через браузер Google Chrome.

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

 
 
 
 
 
 
.
 
 
.
 
 
.
 
 
.
 

Поддержка браузерами

Тег
	Да	Да	Да	Да	Да

Улучшите свой CSS с помощью этих 5 принципов

Написание CSS — процесс достаточно простой и понятный, тогда почему для этого требуются еще какие-то принципы и best-practices?

По мере увеличения масштабов проекта и количества людей, работающего над ним, всё более и более явно начинают проявляться новые сложности, которые могут вызвать серьезные проблемы в будущем. Дублирование кода, сложные цепочки переопределения свойств, использование !important, оставшиеся и неиспользуемые CSS-свойства от удаленных HTML-элементов и так далее. Такой код сложнее читать и исправлять.

Написание CSS на профессиональном уровне сделает код более поддерживаемым, расширяемым, понятным и чистым. Давайте рассмотрим 5 простых и очень эффективным принципов, которые выведут ваш CSS на новый уровень

Принцип именования

«В компьютерных науках существует только две сложные вещи: инвалидация кеша и именование» – Фил Карлтон

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

Принцип низкой специфичности

Переопределение CSS-свойств является очень полезным, но в более сложных проектах всё может достаточно быстро выйти из-под контроля. Цепочки переопределения могут стать очень длинными и сложными, что вынудит вас использовать !important для решения проблем специфичности, в которых можно легко потеряться при отладке кода или добавлении новых функций

/* Селектор с низкой специфичностью */ .card <> /* Селекторы с высокой специфичностью */ .card .title <> .blog-list .card img <> .blog-list .card.featured .title <> #js-blog-list .blog-list .card img <> 

Браузер и специфичность

Одно из преимуществ следования принципу низкой специфичности — это производительность. Браузеры парсят CSS справа налево.

Давайте взглянем на следующий пример:

.blog-list .card img <> 

Браузеры «прочитают» селектор следующим образом:

1. Найти все теги на странице
2. Из них выбрать элементы, которые являются потомками класса .card
3. Из них выбрать элементы, которые являются потомками класса .blog-list

/* Селектор с низкой специфичностью */ .card <> /* Замена селекторам с высокой специфичностью */ .card__title <> .blogList__image <> .blogList__title--featured <> .blogList__img--special <> 

/* Без использования принципа DRY */ .warningStatus < padding: 0.5rem; font-weight: bold; color: #eba834; >.errorStatus < padding: 0.5rem; font-weight: bold; color: #eb3d34; >.form-errorStatus

/* С использованием принципа DRY */ .status < padding: 0.5rem; font-weight: bold; >.status--warning < color: #eba834; >.status--error < color: #eb3d34; >.form__status

.button < padding: 1rem 2rem; font-size: 2rem; border-radius: 0.2rem; background-color: #eb4934; color: #fff; font-weight: bold; >.button--secondary

/* Общие стили */ .button < padding: 1rem 2rem; font-weight: bold; color: #fff; >/* Расширения стиля */ .button--radialBorder < border-radius: 0.2rem; >.button--large < font-size: 2rem; >.button--primary < background-color: #eb4934; >.button--secondary

.card < padding: 1rem; >.blog-list .card

 .card < padding: 1rem; >.blogList__card