I use Markdown-inspired headings in my CSS comments, to structure my code and make it easier to parse visually and maintain. I tend to use two, sometimes three levels of headings.
For the first two levels, I use a rather verbose syntax. But it’s not too hard to type (especially in the SCSS syntax), and it makes it easier to spot the different headings.
Is it a good style? I don’t know. I’ve only ever used it in my personal projects. But I like it, so I’m sharing it.
/* ================= */
/* LEVEL ONE HEADING */
/* ================= */
/* ----------------- */
/* Level two heading */
/* ----------------- */
/* ### Level three heading ### */
/* Additional information goes here. */
And in SCSS:
// =================
// LEVEL ONE HEADING
// =================
// -----------------
// Level two heading
// -----------------
// ### Level three heading ###
// Additional information goes here.
Differences from Markdown
I’m not using strict Markdown in the heading-comment style above. The main differences are:
-
The top lines of equals (
=====
) and hyphens (-----
) are not part of the Markdown syntax for headings. I use them because I feel it makes the headings more visible and visually balanced, but processed as Markdown they would produce<p>=====</p>
and<hr />
, respectively. -
I’m using uppercase letters for the top level heading-comment, which is an arbitrary style decision.