Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

CSS Coding Style: Difference between revisions

From MoodleDocs
Line 169: Line 169:


=== LESS and Other CSS Preprocessors ===
=== LESS and Other CSS Preprocessors ===
[http://lesscss.org/ LESS] is not CSS. LESS will be evaluated according to the [http://lesscss.org/#docs LESS documentation]. If the LESS is valid according to the LESS documentation, and does not result in invalid CSS when compiled, it does not need to be further changed, revised, updated, or documented. The same goes for SASS and any other preprocessor languages coming down the pike.  It's important that your LESS or SASS files be clear and accessible to others, and where the rules above apply, for example, with regard to line breaks, and syntax, please attempt to follow the style guidelines above.  
[http://lesscss.org/ LESS] is not CSS. LESS will be evaluated according to the [http://lesscss.org/#docs LESS documentation]. If the LESS is valid according to the LESS documentation, and does not result in invalid CSS when compiled, it does not need to be further changed, revised, updated, or documented. The same goes for SASS and any other preprocessor languages coming down the pike.  It's important that your LESS or SASS files be clear and accessible to others, and where the rules above apply, for example, with regard to line breaks and syntax, please follow them.  


Some additional features allowed in LESS or SASS conflict with CSS usage. One example is inline comments in LESS. However, these inline comments do not appear in the compiled CSS file. The rule of thumb is that so long as the feature is part of the documented LESS or SASS feature set, is clear and usable by other developers (who have read the LESS or SASS documentation), and does not break or interfere with the functioning of the compressed CSS file, we let it stand in peer review.
Some additional features allowed in LESS or SASS conflict with CSS usage. One example is inline comments in LESS. However, these inline comments do not appear in the compiled CSS file. The rule of thumb is that so long as the feature is part of the documented LESS or SASS feature set, is clear and usable by other developers (who have read the LESS or SASS documentation), and does not break or interfere with the functioning of the compressed CSS file, we let it stand in peer review.

Revision as of 14:19, 9 May 2013

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.


The Moodle CSS coding style

Overview

Scope

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

Goals

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

  • simplicity
  • readability
  • tool friendliness

Naming Conventions

Within plugins, CSS files are normally named *styles.css*.

In the theme, files can be named according to the theme designer's wishes but should:

  • use lowercase letters only
  • be as short as possible

Block Style

  • Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
  • Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
  • The closing brace should use the same level of indentation as the opening selector.
  • Add a blank line between sections, but leave no lines between blocks in a section.

Correct

@media only screen and (min-width: 768px) {

   #selector_one,
   #selector_two {
       color: #fff;
       background-color: #000;
   }

}

Incorrect

#selector_one, #selector_two { color: #fff; background-color: #000; }

Selectors

  • Follow Moodle Coding style for naming selectors.
  • Names should be simple English lowercase words.
  • Words should be separated by underscores or hyphens.
  • Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
  • Use semantic names: names tell what this is instead of what should it look like.
  • Avoid using IDs as selectors wherever possible. IDs are a tad faster, but far more difficult to maintain and override. If you can't write the needed selectors successfully without using an ID, then submit a Tracker ticket to have classnames added.

Correct

#selector_name {

   color: #fff;

}

or

#selector-name {

   color: #fff;

}

Incorrect

#selName {

   color: #fff;

}

or

#Sel-Name {

   color: #fff;

}

Properties and Values

  • Properties should be followed by a colon and a space, unless it is the last rule in the list of CSS mark-up.
  • All properties and values should be lowercase, except for font names and vendor-specific properties.
  • For color codes, avoid uppercase, and use the shorthand version where possible, (e.g: #fff instead of #ffffff or #c06 instead of #cc0066). If you use HSLA or RGBA, provide a HEX fallback (always).
  • Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
  • Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
  • Do not use !important unless the is a good reason! If you need to use !important, something is wrong with the CSS you are trying to override. Rather than adding more problematic CSS, submit a Tracker ticket to get the existing problem fixed.

Correct

#selector {

   color: #fff;

}

Correct

#selector {

   color: #fff;
   color: hsla(0, 0%, 100%, 1);

}

Incorrect

#selector {

   color: hsla(0, 0%, 100%, 1);

}


Incorrect

#selector {

   color: #FFFFFF !important;

}

Documentation and Comments

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file. /**

  • base.css
  • Contains base styles for theme basic.
  • /

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality: /**

  • SCORM Navigation Sidebar
  • /

Use single-line comments to provide more information to other developers about a single rule or small subset of rules: /* Required because YUI resets add a black border to all tables */

Progressive Enhancement

  • Code should follow the Moodle principle of progressive enhancement for all supported browsers for that specific version of Moodle. Supported browsers are listed in the Release notes for the Moodle version.
  • Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
  • Use vendor prefixes only when the supported browser in question does not support the unprefixed property. Outdated vendor prefixes can be removed. Use Can I use or like resource to determine what's supported.

#selector {

   background-color: #444; /* Fallback for browsers that don't support gradients */
   filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9 */
   background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome */
   background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+ */
   background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6 */
   background-image: -ms-linear-gradient(top, #444, #999); /* IE10 */
   background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+ */
   background-image: linear-gradient(top, #444, #999); /* W3C Standard */

}

Browser Hacks

  • Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

.ie7 .forum-post {

   min-height: 1px;

}

  • It is not necessary to include hacks for versions of browsers that Moodle Core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

LESS and Other CSS Preprocessors

LESS is not CSS. LESS will be evaluated according to the LESS documentation. If the LESS is valid according to the LESS documentation, and does not result in invalid CSS when compiled, it does not need to be further changed, revised, updated, or documented. The same goes for SASS and any other preprocessor languages coming down the pike. It's important that your LESS or SASS files be clear and accessible to others, and where the rules above apply, for example, with regard to line breaks and syntax, please follow them.

Some additional features allowed in LESS or SASS conflict with CSS usage. One example is inline comments in LESS. However, these inline comments do not appear in the compiled CSS file. The rule of thumb is that so long as the feature is part of the documented LESS or SASS feature set, is clear and usable by other developers (who have read the LESS or SASS documentation), and does not break or interfere with the functioning of the compressed CSS file, we let it stand in peer review.

Credits

This document was drawn from the following sources:

  1. The WordPress CSS Coding Standards

See Also