Let’s Write Beautiful CSS Comments

your code isn't as self-explanatory as you think it is. Every line you write makes more sense to you than it does to anybody else on your team. And given enough time, even you will forget how your stuff works. This is doubly true for CSS. Think about it: you can't really break down your CSS into tons of little descriptive functions the way you can with JavaScript or Ruby. Breaking declaration blocks into tiny, reusable classes doesn't pack the same descriptive punch as good function names. Self-documenting CSS isn't a thing.

There's often loads of intention behind why styles should be applied to a given element, but those ideas get lost in translation as we write CSS. Human intention rarely shines through those cold, hard selectors, properties, and values. This is one of the reasons it’s so notoriously difficult to maintain other people’s CSS, and it really stifles collaboration. Fortunately, it can be remedied with the use of comments. Writing high-quality comments gives us a way to communicate intention to our teammates. If we comment beautifully, we work together beautifully. This post is about those beautiful comments.

By the way, If you’re using CSS comments as a way to generate a styleguide with something like Knyle Style Sheets or hologram, good for you, but that’s not what this post is about. It’s more about what makes for a useful comment.

Beautiful Comments Are Plentiful First thing's first: you don't write enough comments. It's the truth. I realize it's not fun to hear. I'm sorry. But please write more comments. If you don't comment your CSS, you'll confuse other people looking at your code, and, more embarrassingly, you'll confuse future you. If you do comment CSS, everybody will be less confused, and things will be accidentally broken less often. You will be popular and generally well-liked, and people will remember to send you cards on your birthday. Comment more.

Knowing when and what to comment can be tricky, so here are a couple rules of thumb to help you comment more frequently and usefully:

Always document hacky code. If you find a tricky solution for something on Stack Overflow, be sure to describe what you were fixing, and include the URL to give context to future developers.

Consistency is key. You may want to work with your team to decide on an agreed-upon style. If you don't have a style guide set in place for comments, here are some baseline rules to make your comments look great. These are taken straight from Nicolas Gallagher's idiomatic-css repo, which provides much more comprehensive style rules if you're interested.

Place comments on a new line above their subject. Keep line-length to a sensible maximum, e.g., 80 columns. Make liberal use of comments to break CSS code into discrete sections. Use "sentence case" comments and consistent text indentation. You can get way more fancy than these simple rules, but this is a solid foundation for making comments beautiful—in every sense of the word.

Beautiful Comments Are Only a Little More Difficult Commenting CSS is important, and we should do more of it. We ought to be on the lookout for opportunities to add thoughtful comments, and we should take a little bit of time to make our comments look good and official. All these things take a little bit of elbow grease, but it’s a small amount of elbow grease.

I encourage you to get into the rhythm of putting more effort into your CSS comments. It’s a small investment, and it’s a noble one. Making a habit of writing beautiful comments means getting into the habit of communicating clearly with your teammates. If you can communicate clearly, you can collaborate effectively. And if you can collaborate effectively, you can build some seriously impressive things.

Souce by:https://seesparkbox.com/foundry/lets_write_beautiful_css_comments?utm_source=Responsive+Design+Weekly&utm_campaign=c57c3762ae-Responsive_Design_Weekly_208&utm_medium=email&utm_term=0_df65b6d7c8-c57c3762ae-34049697&goal=0_df65b6d7c8-c57c3762ae-34049697&mc_cid=c57c3762ae&mc_eid=0f888691f7