Лучшая практика для оформления комментариев в HTML, CSS?

Question

[dhat]

Где-то встречал style guide как оформлять грамотно комментарии. Понятно, что одного правила нету, поэтому хотелось бы почитать про все практики профессионалов дела.

Также, хочется инструкции, как настроить воркфлоу для быстрого и удобного их применения. Юзаю Атом. Насколько я понимаю это в сниппетах или в Эммете настраивать? Какие сниппеты оптимально содавать?

Answer 1

[Сергей delphinpro]

Основное правило комментариев - нужно комментировать не "что это", а "зачем это". Плюс комментарии-документация.

Касаемо CSS:
хорошо будет, если вы будете объяснять "магические числа"

margin-top: 2px; // выравниваем по вертикали, по-другому никак

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

<!-- BEGIN: .big-block -->
... 100500 строк кода разметки
<!-- END: .big-block -->

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

Answer 2

[Dark Hole]

Начнем со сниппетов.

В Atom есть очень хороший стандартный сниппет - CTRL + /. Как вы уже догадались, он создает комментарий и, кстати, очень хорошо работает с выделением. Что касается специализированых сниппетов - если поставить плагин на JS(если не ошибаюсь) добавляются всякие там TODO и HACK.
Что касается оформления комментариев - тут так же, как и с кодом: главное - красиво и читабельно. Стоит уяснить всего две простые вещи: комментируйте только основные моменты и отличайте коммиты от комментов. Первое - просто. Не нужно пояснять каждую команду, объясняйте, что происходит, для чего та функция или переменная. Второе - сложнее. Нужно понимать, чтто в коммитах объясняют ПОЧЕМУ вы исправили и дополнили код, а в комментариях именно про общую картину.

Удачных комментариев)

Comments

[dhat]

Проблема CTRL + / в Атоме - он закомменчивает всю строку, а не так как в Саблайме только выделенный текст :(

[Dark Hole]

dhat: раньше вроде не всю строку... но ладно, коммьюнити Атома об этом спросите

Answer 3

[Ivan Bogachev]

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

// @name Button
// @description Your standard form button.
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// @state .primary - Indicates button is the primary action.
// @state .smaller - A smaller button
// 
// @markup
//   <button>This is a button</button>

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

Comments

[dhat]

Это сложновато, если честно не совсем понятно.