dhat
@dhat

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

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

Также, хочется инструкции, как настроить воркфлоу для быстрого и удобного их применения. Юзаю Атом. Насколько я понимаю это в сниппетах или в Эммете настраивать? Какие сниппеты оптимально содавать?
  • Вопрос задан
  • 1998 просмотров
Решения вопроса 2
delphinpro
@delphinpro Куратор тега CSS
frontend developer
Основное правило комментариев - нужно комментировать не "что это", а "зачем это". Плюс комментарии-документация.

Касаемо CSS:
хорошо будет, если вы будете объяснять "магические числа"
margin-top: 2px; // выравниваем по вертикали, по-другому никак


Касаемо HTML:
программисту, который будет работать с вашей версткой будет удобно, если вы будете обозначать начало и конец больших блоков на странице
<!-- BEGIN: .big-block -->
... 100500 строк кода разметки
<!-- END: .big-block -->


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

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

Удачных комментариев)
Ответ написан
Пригласить эксперта
Ответы на вопрос 1
sfi0zy
@sfi0zy Куратор тега CSS
Creative frontend developer
Хочется также добавить к ответу Сергей , что в долгоживущих проектах может оказаться очень не лишним из комментариев 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 для них - и быстро что-то доделать / добавить / убрать.
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы