The cognitive overhead of working with CSS is huge. With so much to be aware of, and so many project-specific nuances to remember, the worst situation most developers find themselves in is being the-person-who-didn’t-write-this-code. Remembering your own classes, rules, objects, and helpers is manageable to an extent, but anyone inheriting CSS barely stands a chance.
CSS needs more comments.
As CSS is something of a declarative language that doesn’t really leave much of a paper-trail, it is often hard to discern—from looking at the CSS alone—
- whether some CSS relies on other code elsewhere;
- what effect changing some code will have elsewhere;
- where else some CSS might be used;
- what styles something might inherit (intentionally or otherwise);
- what styles something might pass on (intentionally or otherwise);
- where the author intended a piece of CSS to be used.
This doesn’t even take into account some of CSS’ many quirks—such as various sates of
overflow triggering block formatting context, or certain transform properties triggering hardware acceleration—that make it even more baffling to developers inheriting projects.
As a result of CSS not telling its own story very well, it is a language that really does benefit from being heavily commented.
As a rule, you should comment anything that isn’t immediately obvious from the code alone. That is to say, there is no need to tell someone that
color: red; will make something red, but if you’re using
overflow: hidden; to clear floats—as opposed to clipping an element’s overflow—this is probably something worth documenting.
Reference: css guidelines