CSS Coding Standards

From Habari Project

Revision as of 02:36, 5 November 2010 by chrismeller (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Shorthand

It is not only legal to use shorthand CSS, it is in fact recommended to save space. Thus, instead of:

font-family: Helvetica, Sans-Serif;
font-size: 1em;

You should use:

font: 1em Helvetica, Sans-Serif;

This isn't applicable however if using shorthand means overwriting cascading CSS with similar CSS simply for the sake of using shorthand. The following example for instance, is wrong:

ul li {
	margin: 0 5px;
}
 
ul li.last-child {
	margin: 0 5px 0 10px;
}

This would be the correct way of changing the left margin:

ul li.last-child {
	margin-left: 10px;
}

In this way, you retain any changes higher up in the hierarchy.

Colors Shorthand

Using shorthand colors is entirely legal, like so:

body {
	color: #222;
}

Color names (white, black, cyan) should not be used, because implementation on all browsers is not the same. Additionally, they provide no added benefit beyond convenience.

Proprietary Styling

It is fully legal to use proprietary styling rules, like for instance -webkit-box-shadow, as long as it doesn't degrade the user experience in any significant way on browsers where it isn't supported.

Also, when doing so, e.g. with -webkit-border-radius, it is recommended that any other similar implementations be supported as well; in this case -moz-border-radius.

Remember the Cascade

It is easy to forget the cascading part of CSS in the heat of battle. However, in order to make future editing of admin.css as effortless as possible, remembering to contain the cascading of styling is paramount.

Because of this, it is also suggested that the !important rule not be used, as it most often means that the cascading isn't being handled properly elsewhere in the CSS.

Sections

Some files, like /system/admin/css/admin.css, can grow quite large, and require some measure of organization to remain usable. For this, 'sections' are employed, which loosely group definitions by the elements they affect. admin.css for instance has sections like The Basics, The Menubar, The Menu, Dropbuttons and so on and so forth.

A section is a commented capitalized section title with a dash to the extreme left in the comment:

/*- FORMS */

And is always preceeded by two line breaks and followed by a single line space.

Sub-sections can be helpful for dividing large sections. The sub-section title should be descriptive, so browsing the CSS file is swift. They looks like this:

/*-- FORM BUTTONS */

The use of the dash to the left of the inside of the comment, makes it easy to step-search through the CSS file for a section, sub-section or simple comment, but searching for '/*- ' (sections) or '/*-- ' (sub-sections) or simply '/* ' (comments).

CSS Code Layout

All style definitions should have one line of space before and after. All CSS rules should be indented with a single tab space, and have a single space between the colon and the value of the rule. Finally, a semi-colon should follow all values, regardless of whether the value is the last in the style definition.

Like so:

body {
	background: #eee;
	font: 1em Helvetica, 'Trebuchet MS', Sans-Serif;
	color: #222;
}

As with any well-formed CSS, notice the apostrophes around 'Trebuchet MS' and the defaulting to Sans-Serif.

For readability and consistency's sake, it is generally recommended that even single-line style definitions be set up in the above manner, and not on a single line, like so:

body { color: #222; }

Inline Comments

When a piece of CSS is inserted for non-obvious reasons, it can be a good idea to leave a small comment for others so as to not have it removed later because it didn't seem to make any immediate sense.

Comments are inserted on the right-hand side of the element they are meant for. If they cover an entire block of code, it would look like this:

body { /* Something insightful goes here */
	background: #eee;
	font: 1em Helvetica, 'Trebuchet MS', Sans-Serif;
	color: #222;
}

If they cover only a single element, it would look like this:

body {
	background: #eee;
	font: 1em Helvetica, 'Trebuchet MS', Sans-Serif; /* Trebuchet MS doesn't match Helvetica well */
	color: #222;
}

Complete Example

This is how the end of one section and the beginning of a new, complete with inline comments, might look:

body {
	background: #eee;
	font: 1em Helvetica, 'Trebuchet MS', Sans-Serif;
	color: #222;
}
 
 
/*- HEADERS */
 
h1, h2 {
	color: #111; /* Redundant comment */
	font-size: 2em;
}
 
h2 {
	font-size: 1.5em;
}
Personal tools