* | [Online Feedback Management System for Education]_ |
CSS Coding Standard
Contents:
General
We are using the Google CSS Style Guide as our primary guide and have made a few changes to suit TEAMMATES project. The Google Style Document shall be used for any topics not covered in this document.
→ We are using Bootstrap front-end framework to ease our styling efforts
Use bootstrap classes wherever possible and as much as possible. In those rare occasions that additional rules are needed, follow the standard given below. |
→ We only have one CSS file for the entire website
Since the golden rule is to use as much bootstrap classes as possible, we do not expect much additional css to be written. Thus we shall use just one file teammatesCommon.css to contain all the additional css. Also, having just one file helps to isolate the css rules in one file rather than to search multiple files. Finally there is a performance boost when only one file is used as there are fewer HTML requests and better use of caching. |
→ We are not using CSS3 selectors --reconsider this rule when IE12 releases
Although they are powerful, cross browser compatibility is difficult to achieve and many rules are supported by different browsers starting from different versions (refer: W3CSchools List). Also, we can stick to more functional names for the css and use classes to achieve our needs → more readable and easier to manage. |
CSS Files
→ Include any additional css specifications in one file - teammatesCommon.css
→ In the future if we have more files, CSS file includes must be done using <link> tags in the html/jsp files and NOT using @import in other css files.
<link rel=”stylesheets” href=”../teammatesCommon.css” type=”text/css”> |
@import “teammatesCommon.css”; |
@import can be slow and may result in the page being rendered without css for a while before the page magically comes to life. As of now we are using css files as stylers of html pages and thus the dependency must be clearly visible in the html page. |
→ NO inline style sheets or inline styles in the html/jsp files
/* write styles only in the external file teammatesCommon.css */ #mainDiv { border: thin solid black; color:white; margin: auto; } |
<!-- no inline stylesheets → <style> #mainDiv { color: white; } </style> <!-- no inline styling in tags --> <div id=”mainDiv” style=”border: thin solid black; margin: auto”> |
The whole idea is to have Separation of Concerns (SoC). If css rules are specified everywhere, editing them in the future will be a hassle and redundant overriding of css rules may occur. If all are in one place management is also easier. |
Sections
→ teammatesCommon.css has been divided into 4 sections - Generic, NavBar, Header, MainContent. Place the new css rules in the appropriate section.
By segmenting the file in this logical way, it is easy to locate css rules and to ensure that a new rule being added is not already present. |
Selectors
Selector formatting:
→ The selector(s) must be specified in separate lines
/* Each selector in a new line */ .button-sort-ascending:hover, .button-sort-none:hover { cursor: pointer; } |
/* do not write them in the same line */ .button-sort-ascending:hover, .button-sort-none:hover { cursor: pointer; } |
This eases reading as well as helps in revision control as conflicts reduce. |
→ Group related/hierarchical style specifications (eg :hover, child specifier, etc) and provide an additional indent to the more specific selector --refer to here for examples
This gives a nice hierarchical structure to the file and helps to visually group css rules by indentation. In addition this gives an immediate idea as to how certain classes are being used in the HTML files (from the hierarchy) without actually reading HTML files. |
Use of Efficient selectors
→ Do not qualify class/ID selectors using tag names (do not use: div.mainContent, simply use .mainContent) -- refer to Writing efficient CSS for examples
This speeds up the css match lookup. If such a qualification is actually required, either use another class on top of this to change the style or use a completely different class to start with. In any case, if this kind of qualification is needed, then probably the class has not been named well enough (see naming standards for classes). |
→ Use Child selector rather than descendant selector (use ‘#container > span’ rather than ‘#container span’) -- refer to Writing efficient CSS for examples
This is a strong recommendation as descendant selector is extremely expensive, especially when the specified ancestor has a lot of descendants. |
Classes
Naming Standards
→ Use all lowercase letters
→ Separate words with hyphens (‘-’) and no other separator
→ We use 2 kinds of classes: Atomic and Component
/* Component Class */ .comment-list .sort-icon /* Atomic Class */ .align-center .border-gray |
/* do not use these */ .commentList .sort_icon .centeralign |
Atomic Classes describe atomic attributes like border-gray, align-center that can be used on any element. They have at most 2 rules in them. Start their names with the attribute, followed by the value. (eg: .align-center and not .center-align) Component Classes are used for components that have a particular role that (preferably) recurs in multiple pages. To name these classes, describe the function of the element rather than its location (eg: .panel-details rather than .top-details-box) |
→ When adding classes to style elements in the page, follow the following steps:
⇒ Try and style the entire component using bootstrap
⇒ For any additional css, if the component is used in many places create a functional name for the class
⇒ If the component does not have any recurring function, utilise the generic classes to achieve the styling.
Exception: If a particular element requires too many generic classes ( > 5) create a functional class name for it.
Attributes
Order of attributes
→ Alphabetize the attributes, disregarding any browser prefix.
→ All browser prefixed versions of an attribute must be written together.
/* code the attributes in alphabetical order */ .sort-icon { display: block; float: right; height: 17px; margin-top: 1px; width: 12px; } |
.sort-icon { width: 12px; height: 17px; display: block; margin-top: 1px; float: right; } |
This way looking for an attribute is faster. |
Attribute formatting
→ Semicolon after every attribute specification
→ Space after colon
→ Drop the units for 0 values (eg: margin: 0)
→ All attribute(s) are to be specified in individual lines
→ Attributes must have one more indentation than the selector
→ indent attributes that require browser specifications so that the actual attribute being declared are in one column --refer to Writing Your Best Code for examples
General details
→ Use shorthands as much as possible (eg border: 2px 0 1px 4px)
→ DO NOT use !important specifier
/* not recommended */ margin: 10px 0 !important; |
Using the !important specifier overrides the natural flow of specificity and cascading hierarchy of css styles. Unless absolutely necessary do not use it. If there is such a situation clearly state the reason with comments (/* */). |