CSS comments code style

Development
#1

We currently don’t have an explicit code style for the CSS comments in the HTML & CSS Code Style.

The most common style is the single line comment (eg /* this is a comment */).
Three other less common comment style can be found from time to time.

Inline with two opening stars:

/** This is a comment */

Multilines:

/*
This is a comment
*/

Multilines + two opening stars:

/**
This is a comment
*/

I propose to avoid the “two opening stars” form.

From there I can think of two alternatives.

Alternative 1
Stay with the inline form, even for multilines comments.

For instance:

/* This is a ...  */
/* ... two lines comment.  */

Alternative 2
Use the multiline form for multilines comments.

For instance:

/* This is a single line comment  */

/*
This is a ...
... two lines comment
*/

/*
This should be on a single line.
*/

WDYT?

#2

My opinion, and I have no dog in this fight, but Alternative 2 is cleaner and easier to maintain.

#3

Hi Manuel,

I see this as a mistake (typo). The double start doesn’t make sense here (for CSS) when the comment is on a single line.

I haven’t seen this and that’s not the style I use. I’m not that fond of it.

I haven’t seen this either and that’s not what I commonly use.

The style I used so far is this:

  • single line / short comment (less than 120 chars)
/* This is a short comment */
  • multiple line / long comment (more than 120 chars)
/* This is a very long comment that wraps
  on multiple lines ...
  and so on. */
  • multiple line / section comment
/**
 * Section title
 */

and I vote to keep this :slight_smile: . Note that a strong argument for the first two (short and long comment style) is that it matches the style we use for XML comments. XML has only one syntax for comments, as is the case with CSS, and we have to use it for single and multiple line comments. The style we use for XML comments is:

  • short comment (less than 120 chars)
<!-- This is a short comment -->
  • long comment (more than 120 chars)
<!-- This is a very long comment that wraps
  on multiple lines ...
  and so on. -->

The indentation should be 2 chars for both CSS and XML.

Now regarding your proposal:

  • Alternative 1: I don’t see the point of duplicating the comment syntax on each line
  • Alternative 2: I don’t like the lack of indentation, and I feel the empty lines before and after make the comment standout a bit too much (like a section separator).

Thanks,
Marius

#4

Thanks for the explanations, I had missed some details of the current code style.

I’ve update the documentation with a CSS comments sections, here is the diff.

I’ve tried to explain when to use the “sectioning” style but the current sentence is not very precise.

#5

Looks good to me. Thanks for handling his.