CSS Coding Standards

First up,
Thanks to Nick Lewis for kicking this off at
http://www.nicklewis.org/node/966.

The standards are slightly different to those he prosposed.

For the most part, the standards describe how core css files currently function.
The main expection is that I propose a single line between each rule, to aid readability.

I do realise that just adding a standards page, without prolonged discussion, is perhaps controversial.

I don't anticpate changing Drupal 6 core css files at all.

Hopefully we will reach some agreement,
then the rules can be added to the Coder module for Drupal 7.
Once that happens, we can create patches, if necessary, for core files.

Myself and Stella spoke to Gabor.

Stella intends to add the CSS and Javascript rules to Drupal 6 version of coder.

Once that happens we can work on patches for core.

In principle, Gabor agrees that changing core css code to comply with coding standards does not constitute an API change [even if the standards were added retrospectively].

So these standards may yet apply to core for Drupal 6.

I'm not a huge fan of the "multiple selectors must be on one line". Very long selectors could make that line hundreds of lines long. Something like, for example:

#casetracker-status-cant-reproduce td.sorted.odd, #casetracker-status-resolved td.sorted.odd, #casetracker-status-needs-work td.sorted.odd, [etc.] {

versus:

Gah, posted before I wanted to (usability problem: I /expect/ a Preview button because I don't "see" the live Preview). Anyways, I'd want it both ways: small selectors can be placed on one line, but very large ones like the above should be split for readability's sake.

One line is a terrible standard, I vote no to that as well... Please remember we DO have CSS minification, whitespace is irrelevant, readability is much more important .

Tj Holowaychuk

Vision Media - Victoria BC Web Design
Victoria British Columbia Web Design School

Each property should end in a semi-colon.
[Even though this isn't strictly necessary for the last rule, it aids readability.]

Please remove that (too limited) justification in brackets. Just like the trailing comma in multi-line arrays in PHP, the standard also makes patches against existing code cleaner.

There should be a single empty line between rules.

-1 on this rule, because most stylesheets become unclear this way; however, +1 for separating related styles into "blocks" using one or two single empty lines between rules.
For example,

meh... the <code> filter does not properly display these empty lines and blocks. Hope you get the point anyway - a) group styles that belong together (i.e. apply on the same target, f.e. a block), and b) do not separate styles within one grouping block, but separate styles for different target elements or output objects with empty lines.

Daniel F. Kudwien
unleashed mind

I have been finding indentation on related and nested blocks to provide better readability. I personally +1 the single space between declarations, but between distinct blocks I use comments. Multiline comments for the major blocks, and then single line comments for the tiny bits that need more explanation. Using the same example, it would be something like this:

I find when there starts to be 1000+ lines of css to dig through, this comes in very handy.

Note: The spacing in the code element seems to be off.

+1 for removing the "justification in brackets".

As for "There should be a single empty line between rules.", I'm also +1 to this (as opposed to sun). Sun seems to be using the "no lines between rules" as an indication of a "block" of CSS-related selectors. My opinion on that is: you can accomplish the block just as well, and far more clearly, with comments detailing what the block is. So I'm +1 to a single empty line, and would challenge Sun to clearly document his "blocks" (which I certainly agree with) with explicit comments, instead of inferred no-lines.

Great to see some instant feedback!
[Addi was right! - Put it straight in the handbook - and people will talk!]

@Morbus
While I see some justification is being able to use both multiple selectors on one line,
but use multiple lines if necessary, I'd rather be consistent.

I propose single selector per line,
space follow by brace after the last selector.

I really like the single line between rules, and blocks of related rules should be commented.

How about a comment after the last line in a group of rules to indicate the end of that group?

In general, should the PHP comment guidelines also apply to CSS?
[I spoke to Neil Drumm - he is considering improving api.drupal.org to include js and css files too, btw].

Justification in brackets removed.

Alan

There is no reason CSS could not use a JavaDoc-like syntax. I have not had time to work on my CSSDoc syntax specification however that was the goal..
This basic structure is what I use on all projects http://vision-media.ca/sites/all/themes/light/style.css

Laying out the stylesheet like really is quite logical and simplistic, should not be an issue for anyone to maintain. It is all about maintainability, readability, not saving space or performance.

Tj Holowaychuk

Vision Media - Victoria BC Web Design
Victoria British Columbia Web Design School

I also disagree with Nick's acceptance towards single-liners. Just because it may only have one rule at the moment does not mean it will stay that way, and most likely will not. So bumping down those lines is really just a hassle.

Tj Holowaychuk

Vision Media - Victoria BC Web Design
Victoria British Columbia Web Design School

I like putting my selectors on multiple lines. I can see why putting shorter length selectors on a single line would be convenient, I prefer to error on the side of consistency.

For me, it comes down to readability of the stylesheets. Drupal sites can be very complex beasts and the size of them can be quite large. Then you add the fact that in this community there will be several people looking at them and editing them, we will want to remove as much confusion as possible.

"While I see some justification is being able to use both multiple selectors on one line, but use multiple lines if necessary, I'd rather be consistent." - than I'd vote for "multiple selectors on multiple lines". The dangers inherent in single-line usage is just too great.

+1 for:

• One selector per line in all cases - less error prone
• Standardizing on CSSDoc comment syntax, which is the closest thing to a standard that we have and it very friendly for folks who code almost any regular language

I am not sure about indentation of 'sub'-blocks as a whole as suggested by Zarabadoo (obviously the rules inside the braces should be indented 2 spaces). I can see how this could improve readability in some cases, but I would like to see a very very clear definition of when this indentation applies (i.e. one specific enough that we could write a coder rule for it).

+1 for a single blank line between rules
+1 for blocks of rules being "separated" or distinguished by comments just above them

As for multiple selectors on one line, not quite sure, which I prefer, but it's hard for Coder to support both methods :) So I'm probably leaning towards one per line,.... I dunno.... I keep changing my mind.

Morbus: can you outline some of the inherent dangers you see with single-line usage?

-1 for Zarabadoo's proposal on indenting blocks.

In the doc, you have an "Other" section in which you say "Header Comment Blocks, block level comments, filenames should follow the PHP coding standards." I would prefer if you actually specify what those are in the CSS standards doc. It would prevent users having to flip between docs. This is what I'm doing for the JS standards doc after receiving feedback from pwolanin and others today.

It might be an idea to specifically state what the indentation / spacing standard is, i.e. 2 spaces. I would like there to be a standard for one space after the colon. I think it is implied in the examples above, but I'm not sure you stated it.

Cheers,
Stella

+1 for a single blank line between rules
+1 for blocks of rules being "separated" or distinguished by comments just above them

-1 for indenting (too hard to manage, better to use comments for related chunks)
-1 for multiple selectors per line -- I have been burned by this so many times, not seeing that there was another selector on the line as opposed to just a really long one

New standards proposals:
- Alphabetizing properties. It sounds kinda hokey at first, but after seeing it pop up in a couple of "best practices" lists, we started doing this a year or so ago and it's awesome.
- Color hex codes instead of names (#ffffff instead of white) -- for better scannability and accuracy
- Always using hyphens in class names, no underscores

~~~
{ Drupal Themes by TopNotchThemes } Gorgeous Drupal 5 & 6 designs with Views/Panels 2 support, plus Ubercart themes!

+1 for alphabetizing properties. I've been doing that already on hook_menu and Form API arrays and, yep, definitely agree - it increases readability, scannability, and eases expectations. +1 for color hex codes, but then you go and say "#ffffff" instead of "#fff" (ideally, though, this is a "soft +1" from me - if you want the most accuracy, you'd use rgb(#, #, #), and I don't consider "#ff0" more "scannable" than say, "blue" or "red"; I only agree cos I practice "hex codes only" too). +1 for hyphens too. Another one I use everyday, and consistent with Drupal core's existing practices (i.e., there's no reason to argue against it, cos core's already doing it ;)).

Here's my 2 cents :)

+ 1 on hex
+ 1 on single line between rules
+ 1 for blocks of rules being "separated" or distinguished by comments just above them
+ 1 for Always using hyphens in class names, no underscores
+ 1 for alphabetizing properties. Does sound a little hokey, but I'll go with it :)
+ 1 for each link ending in a semicolon

- 1 on indentation
- 1 on multiple selectors on 1 line, for consistency sake, while it will surely be annoying in certain cases

+ 2 more...

1 - always use double quotes in HTML attributes, ie. <div class="class-name"> as opposed to <div class='class-name'> (though this is more regular coding standards, I had to say it)

2 - 1 space between property: & value, border: none; as opposed to border:none;

What about comments? What do you guys do? I've tried a few different ways in the past, but I find this works the best for me:

/*------------------------------------------------------------------------
 * MODULE SUPPORT
 *-----------------------------------------------------------------------*/

/* administration menu */
#admin-menu {
  font-size: .95em;
}

/* update status */
.versions table,
.versions td,
.versions th {
  border: none;
  overflow: auto;
}

Good to see that consensus of some kind is emerging from the healthy discussion.
I've learned so many things, CSSdoc syntax, alphabetizing comments, indentation, etc.

It nice to step back briefly and ponder the reason for standards.
If the CSS works, then why should we care?

As I see it, coding standards are to allow developers to work closer together.
Having a common langauge means we can all contribute to the same project,
without the code becoming an ugly variant of styles.

I believe it's important that all code added to drupal.org, both core and contrib should follow the standards.
I realise that some people will heartily disagree with some of the standards, and try to rail against it in their own projects.

Please think again.

Every project can benefit from other people submitting code reviews, both manual and automatic, and from patches.
Where your code is outside the standards, you present a barrier, however small, to such co-operation.

As well as that, it may be that Coder module ratings could be used as a metric to rate projects [I certainly hope it will],
and your project would suffer.

Onwards with the discussion.

Alan

I have made the following updates.

Selectors are now one to a line.
Alphabetizing rule added.
Added rule specifying full hex values for colors.

I have addded a note on writing valid css, which needs review.
I have added a note on CSS comments, which needs review.

Indendation looks unlikey to get added, unless someone can come up with a very clear rule to define its use.

Some more questions.
Uppercase or lowercase?
I certainly prefer uppercase for hex values, but lowercase elsewhere.

Where should our HTML standards go?
Who wants to take that one on?
This is good start
http://groups.drupal.org/node/6355
but it needs to migrate to the handbook, and become a standard.

Alan

Jonathan Christopher writes about his style
http://mondaybynoon.com/2008/09/01/css-organization-methods-and-writing-...

• 1 on hex ... but I strongly believe short hex should be acceptable
• 1 for blocks of rules being "separated" or distinguished by comments just above them
• 1 for Always using hyphens in class names, no underscores
• 1 for alphabetizing properties. Does sound a little hokey, but I'll go with it :)
• 1 for each link ending in a semicolon
  +1 for always use double quotes in HTML attributes
  +1 for space between property: & value, border: none; as opposed to border:none;

0/0 (meh) on single line between rules. Okay, if that's a strong preference. It goes against the whole concept of chunking data for readability, but I can cope.

-1 on indentation (sorry Al -- works in xhtml, but confusing in css)
-1 on multiple selectors on 1 line, for consistency sake, while it will surely be annoying in certain cases
-1 on HEX CAPS. I say play it as it lays. If you're pasting from Colorzilla, it will have caps. If you're typing, it might not. I don't see a gain from imposing a rule on this

I would also add a fuzzier rule: Avoid adding specific IDs/classes from the detail end up. For example, a page ID and class can save a lot in specific IDs and classes on individual fields, lists, etc. Basic example:

is cleaner and preferable to:

There's nothing like having to create a 5,000-line css to accommodate all the individual items that have been given overly detailed mark-up, especially when a simple, identified div container class and/or id are missing.

/rant

Laura
pingVision, LLC (we're hiring)

As far as ordering of the rules I would somewhat agree with alphabetizing it, however I prefer to start with rules that are unlikely to change, then following with those that will. Also I prefer to utilize the box model as my ordering, so display, position, dimensions etc. example:

Tj Holowaychuk

Vision Media - Victoria BC Web Design
Victoria British Columbia Web Design School

What if we everyone got into the common practice of using a site like http://cleancss.com/ to clean up all their css once it was all together. Would this make some people sleep better?

Brandon Buttars
Drupal Theme Development
http://www.odindev.com

The CSSDoc spec needs a lot of work. And I don't think we should be adopting it prematurely.

I was asked to review it by the authors a few months back, but it was quickly apparent it wasn't worth my time. I have 2 major objections to it. One is there are no tools that actually build useful CSSDoc documentation. They list PHPDocumenter, etc, but those won't generate useful CSS documentation for the following reasons because they don't recognize the @rules that CSSdoc has created that differ from PHPdoc.

In other words, the proposed section comments (which don't even use the proper CSSdoc @section syntax) won't be recognized by the automated tools, or worse would apply the comment only to the first ruleset in the section.

And the proposal doesn't follow the full CSSdoc spec. The full CSSdoc spec would require full PHPdoc-block-like syntax for every comment you want to make. i.e. you would need one per css ruleset or per property. That's super code bloat. Inline comments are much better and they are way more compact.

The idea of @css-for, @bugfix, and @section are good, but requiring a full docblock for the @css-for and @bugfix is flawed given the amount of one-off property fixes needed for various browsers. (That's my second objection to CSSdoc.)

If we're not going to follow the full CSSdoc (and I don't think we should), there's no reason to do a half-way CSSdoc standard. That would lead to confusion (follow this part of the spec, but not that.) Now, an @file docblock does make sense, but that is identical to PHPDoc.

So what are we gaining by saying we are using CSSdoc syntax? Confusion over what parts apply to Drupal's standards and a shifting, alpha-level specification. :-\

  - John (JohnAlbin)

Overall I like the standards and I'm sorry to not have participated in the discussion sooner. I have two major annoyances:

1- Not being able to leave CSS rules with one selector AND one property on one line
2- Having a blank line between between each and every rule

I could eventually learn to live with #2, but with much chagrin. #1, not giving it up.

Hopefully this will be revisited soon.

I think its highly unlikely that I will suddenly change my CSS coding practices because of the Drupal coding standards. In contrast, I am more than happy to meet the PHP coding standards, as they actually make the PHP usable.

I always place CSS rules on a single line; ordered alphabetically; in ID, Class, then Element order. This helps me find items quickly, keeps the length short (less scrolling) and knocks out inheritance issues.

But aside from all that, formatting CSS is not important for readability in the same way it is in scripting languages. There are a lot of disagreements in this thread about what is readable and what isn't, which illustrates an important point with CSS: different strokes for different folks.

This problem stems from the fact that CSS can be organised in lots and lots of different ways, whereas a scripting language, for the most part, can not. Its procedural elements MUST be in order. Because of Specificity, CSS can theoretically be in ANY order.

Perhaps we should be focussing on usage standards, not formatting... things like

• lowercase selectors
• hex standards
• use of comments
• splitting layout & design

Actually SASS looks pretty cool: http://sass-lang.com/ ... Anyone used it? I am thinking of giving it a go sometime. How would SASS fit in with this discussion? SASS is an alternative method for coding CSS so that you can have neat things like variables and (actual) nesting of selectors.

I am thinking that SASS would really fly in the face of CSSDoc though (from what I can tell). I suppose it really depends on what the SASS interpreter's output looks like though. As I recall it looks fairly different from vanilla CSS in terms of indentation, spacing, etc... It may alphabetize. But a tool like this could change the way we code CSS as well.

Derek