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.

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:

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

+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.

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

"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

-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-...

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

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)

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

+1 for multiple selectors being on a single line each, with the exception of top level elements (h1, p, etc.). I usually put them together on a single line and if that line were to grow too big you're doing something wrong anyway. ;-)

+1 properties being on a single line.

-1 indentation of properties with spaces. I hate spaces for indentation and I have yet to hear a convincing argument to using spaces in favor of tabs. Use tabs and set your editor to your own preferred tab width. I know 2 spaces is the de facto standard in Drupal php files but we hates it and we wants our tabs, yes, precious...

+1 for a space after property name.

+1 for the semi-colon.

-1 for alphabetizing properties. I prefer to logically group my properties (pretty arbitrary, but it's a habit I picked up when I first learned css back in the olden days):

• width/height
• margin/padding
• background/foreground colors (including images)
• font/text related
• positioning
• etc.

-1 on using uppercase with hex colors; I agree with sun on that one.

I haven't decided what to think about leaving out the empty lines between styles; they do make grouping with short comments easier but it looks like a bit of a jumble to me with larger stylesheets.

The order of properties was already discussed lengthy, perhaps somewhere else. Ordering properties alphabetically is the only standard, everyone, including non-experts in CSS, can follow. Additionally, a logical/boundary/box grouping and ordering did not reach consensus and due to the variety of properties, there most probably cannot be a consensus. When defining standards, we need to make them work for everyone, at any skill level, and everywhere.
Effectively, I've changed my mind regarding the order of properties, and support the alphabetical ordering for its simplicity.

Most concrete changes for coding standards for CSS are being discussed in http://drupal.org/project/issues/search/drupal?issue_tags=coding+standards

The proposal to use lowercase hex colors does not seem to be tackled though.

Thus far I have pretty much refused to be drawn on this topic, but really its time to start putting this to bed and nail it down - atm we're writing CSS for core (and have been for the past two years) with very little guidance - that said there has certainly been efforts to follow the proposed standards less the notable exceptions of alphabetization and comment styles (the latter of which is being followed most of the time - Bartik was a notable exception that used proprietary comment styles based on the maintainers preference - never a good thing for core).

Some things that just makes sense and appear to be developing practices in core:

1. Grouped selectors each on a new line.
2. Each property on a new line.
3. Group declaration blocks (no separating lines), separate groups of declarations with a line and introductory comment.
4. Indent properties with 2 spaces (not a tab or no indentation).

Alphabetized selectors separated by a line is a no-brainer - with one very notable exception - the classic reset which gets pretty absurd if broken out onto a new line for each selector (see the Corolla themes reset, as it was when proposed for core), its much more common and sensible to be like...

Alphabetized properties - good but needs sensible exceptions - such as:

1. Browser specific extension such as -moz, -webkit etc fall back to the actual property, thus -moz-border-image is alphabetized under border-image.
2. Browser specific extensions always precede the actual property.
3. Browser specific extensions are alphabetized.

The above example from Bartik starts looking like this:

As for comments - well... @file docblock makes sense to me, other than that single line comments for short single line comments and docblocks for multiple line comments. Inline type comments are OK but to be avoided and only used for very specific types of comments - such as RTL / LTR comments.

For example:

As you may well infer I am more for a very strict set of rules - I think anything less allows for arbitrary interpretations and will just be messy and impossible to enforce.

I can't see any room here for personal readability preferences - this is a standard for all where readability is one part, a standardized, easily applied set of rules with very few exceptions is the other. On that note exceptions are OK. Attempting to craft a set of hard rules with no exceptions I think will be extremely difficult - in regards to satisfying both readability and sensibility.

So a few parting comments:

1. Alphabetized with a few exceptions is the ONLY reasonable proposal, in two years nothing has come up that betters it.
2. Lets get this done for D8 and lock it in.