Best practice for styling comments in HTML, CSS?

Question

css

Somewhere I met a style guide on how to correctly format comments. It is clear that there is no one rule, so I would like to read about all the practices of business professionals.
Also, I would like instructions on how to set up a workflow for quick and convenient use. Yuzayu Atom. As far as I understand it in snippets or in Emmet to customize? What snippets are best to create?

Answer 1

The main rule of comments - you need to comment not "what is it", but "why is it". Plus comments-documentation.
Regarding CSS:
it will be good if you explain "magic numbers"
Regarding HTML:
it will be convenient for a programmer who will work with your layout if you mark the beginning and end of large blocks on the page

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

CSS also recommends making a table of contents and marking the beginning of a block of code with comments.
I consider this approach a retrograde, in the presence of a large number of preprocessing tools.

Answer 2

I would also like to add to Sergey 's answer that in long-lived projects it may turn out to be very useful from css comments like these:

// @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>

generate human-designer-friendly style guides with all the components that you have (a little personal experience shows that you can typeset individual components and immediately look at them in this style guide - grunt / gulp to help, and then insert them into real pages) . As a result, after some time, with the help of one glance, you can remember what is happening, what components you have in general and how they look - immediately with html examples for them - and quickly finish / add / remove something.