Commenting CSS is critical if you are to inform fellow team members (or even just your future self) why you have written code as you have. Code is re-written all the time, and if clever solutions/hacks are not documented, they can easily be left out; this all to often how style regressions get introduced. Clean, consistent formatting also suggests a level of code quality that contributors will feel inclined to match.
I use a brief header comment to title the file and add a sentence or two about what the file does. This is not only useful for newcomers, but can help identifying source files when looking at built CSS in dev tools.
If it is not 100% clear why a particular rule is in place, comment it. I have borrowed a ‘footnote’ technique I saw Nicolas Gallagher using in normalize.css. It’s awesome because your comments can be as long as you want without them getting in the way of your code.
Files will consist of different parts. I use a standard divider comment to clearly split these parts out, this makes finding things quicker.
Make sure that what ever you choose to be your divider is a ‘snippet’ in all dev’s code editors. To insert a divider in my editor (Sublime Text) all I have to do is type
tab, and it prints it for me. Find out how to setup snippets in Sublime Text 2.
I like to clearly indicate when I’m overriding default styling by using an
@state comment block. When I see an
@state comment, I know the styling that follows it will only take affect if certain criteria are met. A ‘state’ could be screen size, orientation, body classes, pseudo classes, state classes, attributes…almost anything!
Single line breaks
Comment line length
I try to keep the line length of comments under 40 characters. For me it seems to make comments a little more digestible.
Commenting is a small thing, but can have big impact, especially when working on large teams. It doesn’t only inform and guide fellow developers, preventing silly regressions; it underpins a code quality standard.
If code is messy and undocumented, it grants permission for other team members to do the same. Quickly your new shiny code base begins to turn into that all too familiar tangled hacky mess. In society this is known as the ‘broken windows theory’, I would argue this theory applies to code too.