YouTip

Bootstrap CSS Coding Standards ## Syntax * Use two spaces instead of tabs -- this is the only way to guarantee consistent rendering across all environments. * When grouping selectors, place each selector on its own line. * To improve code readability, add a space before the opening curly brace of each declaration block. * The closing curly brace of a declaration block should be on its own line. * Insert a space after the `:` in each declaration statement. * For more accurate error reporting, each declaration should be on its own line. * All declaration statements should end with a semicolon. The semicolon after the last declaration is optional, but omitting it makes your code more prone to errors. * For comma-separated property values, insert a space after each comma (e.g., `box-shadow`). * Do not insert spaces after commas inside `rgb()`, `rgba()`, `hsl()`, `hsla()`, or `rect()` values. This helps distinguish multiple color values (comma only, no space) from multiple property values (comma and space). * For property values or color parameters, omit the leading zero for decimals less than 1 (e.g., `.5` instead of `0.5`; `-.5px` instead of `-0.5px`). * Hexadecimal values should be all lowercase, e.g., `#fff`. Lowercase characters are easier to distinguish when scanning documents because their forms are more distinct. * Use shorthand hexadecimal values whenever possible, e.g., `#fff` instead of `#ffffff`. * Add double quotes to attributes in selectors, e.g., `input`. (http://mathiasbynens.be/notes/unquoted-attribute-values#css), but for code consistency, it's recommended to always include them. * Avoid specifying units for zero values, e.g., use `margin: 0;` instead of `margin: 0px;`. Have questions about the terminology used here? Refer to Wikipedia's (https://zh.wikipedia.org/wiki/%E5%B1%82%E5%8F%A0%E6%A0%B7%E5%BC%8F%E8%A1%A8#.E8.AF.AD.E6.B3.95). /* Bad CSS */.selector, .selector-secondary, .selector { padding:15px; margin:0px 0px 15px; background-color:rgba(0, 0, 0, 0.5); box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF}/* Good CSS */.selector,.selector-secondary,.selector { padding: 15px; margin-bottom: 15px; background-color: rgba(0,0,0,.5); box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;} ## Declaration Order Related property declarations should be grouped together and ordered as follows: 1. Positioning 2. Box model 3. Typographic 4. Visual Since positioning can remove elements from the normal document flow and override box model-related styles, it comes first. The box model comes second because it determines the component's size and position. Other properties only affect the component's _inside_ or do not affect the first two groups, so they come last. For a complete list of properties and their ordering, refer to (https://twitter.github.com/recess). .declaration-order { /* Positioning */ position: absolute; top: 0; right: 0; bottom: 0; left: 0; z-index: 100; /* Box-model */ display: block; float: right; width: 100px; height: 100px; /* Typography */ font: normal 13px "Helvetica Neue", sans-serif; line-height: 1.5; color: #333; text-align: center; /* Visual */ background-color: #f5f5f5; border: 1px solid #e5e5e5; border-radius: 3px; /* Misc */ opacity: 1;} ## Don't Use `@import` Compared to the `` tag, the `@import` directive is much slower. It not only increases the number of requests but also leads to unpredictable problems. Alternatives include: * Using multiple `` elements. * Compiling multiple CSS files into one using CSS preprocessors like Sass or Less. * Utilizing CSS file combination features provided by systems like Rails, Jekyll, or others. Refer to [Steve Souders' article](http://www.stevesouders.com/blog/2009/04/09/dont-use-import/) for more information. @import url("more.css"); ## Media Query Placement Place media queries as close as possible to the relevant rules. Do not bundle them into a single stylesheet or place them at the bottom of the document. If you separate them, they will only be forgotten in the future. Here is a typical example. .element { ... }.element-avatar { ... }.element-selected { ... }@media (min-width: 480px) { .element { ...} .element-avatar { ... } .element-selected { ... }} ## Prefixed Properties When using vendor-prefixed properties, align the values vertically through indentation to facilitate multi-line editing. In Textmate, use **Text → Edit Each Line in Selection** (⌃⌘A). In Sublime Text 2, use **Selection → Add Previous Line** (⌃⇧↑) and **Selection → Add Next Line** (⌃⇧↓). /* Prefixed properties */.selector { -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15); box-shadow: 0 1px 2px rgba(0,0,0,.15);} ## Single-Line Rule Declarations For stylesheets containing **only one declaration**, it's recommended to place the statement on the same line for readability and quick editing. For styles with multiple declarations, they should still be split into multiple lines. The key factor here is error detection -- for example, a CSS validator points out a syntax error on line 183. If it's a single declaration on one line, you won't miss the error; if it's multiple declarations on one line, you have to analyze carefully to avoid missing errors. /* Single declarations on one line */.span1 { width: 60px; }.span2 { width: 140px; }.span3 { width: 220px; }/* Multiple declarations, one per line */.sprite { display: inline-block; width: 16px; height: 15px; background-image: url(../img/sprite.png);}.icon { background-position: 0 0; }.icon-home { background-position: 0 -20px; }.icon-account { background-position: 0 -40px; } ## Shorthand Property Declarations When explicitly setting all values, try to limit the use of shorthand property declarations. Common cases of misuse include: * `padding` * `margin` * `font` * `background` * `border` * `border-radius` In most cases, we don't need to specify all values for shorthand property declarations. For example, HTML heading elements only need top and bottom margin values set, so you only need to override these two when necessary. Overusing shorthand property declarations leads to cluttered code and unnecessary overrides of property values, causing unexpected side effects. MDN (Mozilla Developer Network) has an excellent article on (https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) that is very useful for users unfamiliar with shorthand property declarations and their behavior. /* Bad example */.element { margin: 0 0 10px; background: red; background: url("image.jpg"); border-radius: 3px 3px 0 0;}/* Good example */.element { margin-bottom: 10px; background-color: red; background-image: url("image.jpg"); border-top-left-radius: 3px; border-top-right-radius: 3px;} ## Nesting in Less and Sass Avoid unnecessary nesting. Just because you can nest doesn't mean you should. Use nesting only when necessary to limit styles within a parent element (i.e., descendant selectors) and when there are multiple elements requiring nesting. // Without nesting.table > thead > tr > th { … }.table > thead > tr > td { … }// With nesting.table > thead > tr { > th { … } > td { … }} ## Comments Code is written and maintained by people. Ensure your code is self-descriptive, well-commented, and easy for others to understand. Good code comments convey context and purpose. Do not simply restate component or class names. For longer comments, write complete sentences; for general annotations, concise phrases are fine. /* Bad example *//* Modal header */.modal-header { ...}/* Good example *//* Wrapping element for .modal-title and .modal-close */.modal-header { ...} ## Class Naming * Only lowercase characters and dashes (not underscores or camelCase) should appear in class names. Dashes should be used for naming related classes (similar to namespaces) (e.g., `.btn` and `.btn-danger`). * Avoid overly arbitrary abbreviations. `.btn` stands for _button_, but `.s` doesn't convey any meaning. * Class names should be as short as possible and meaningful. * Use meaningful names. Use organized or purpose-driven names, avoid presentational names. * Prefix new classes based on the closest parent class or base class. * Use `.js-*` classes to indicate behavior (as opposed to styling) and do not include these classes in CSS files. The above rules can also be referenced when naming Sass and Less variables. /* Bad example */.t { ... }.red { ... }.header { ... }/* Good example */.tweet { ... }.important { ... }.tweet-header { ... } ## Selectors * Use classes for generic elements to optimize rendering performance. * For frequently occurring components, avoid attribute selectors (e.g., `[class^="..."]`). Browser performance can be affected by these. * Keep selectors as short as possible, and limit the number of elements making up the selector, recommended not to exceed 3. * **Only** limit a class to its closest parent element (i.e., descendant selectors) when necessary (e.g., when not using prefixed classes -- prefixes are similar to namespaces). Further reading: * (http://markdotto.com/2012/02/16/scope-css-classes-with-prefixes/) * (http://markdotto.com/2012/03/02/stop-the-cascade/) /* Bad example */ span { ... }.page-container #stream .stream-item .tweet .tweet-header .username { ... }.avatar { ... }/* Good example */.avatar { ... }.tweet-header .username { ... }.tweet .avatar { ... } ## Code Organization * Organize code segments by components. * Establish consistent commenting standards. * Use consistent whitespace to separate code into blocks, facilitating scanning of larger documents. * If using multiple CSS files, split them by components rather than pages, because pages can be reorganized, while components are only moved. /* * Component section heading */.element { ... }/* * Component section heading * * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough. */.element { ... }/* Contextual sub-component or modifer */.element-heading { ... } ## Editor Configuration Configure your editor according to the following settings to avoid common code inconsistencies and differences: * Use two spaces instead of tabs (soft-tab, using spaces for tab characters). * Remove trailing whitespace when saving files. * Set file encoding to UTF-8. * Add a blank line at the end of the file. Refer to the documentation and add these configuration details to your project's `.editorconfig` file. For example: [Bootstrap's .editorconfig example](https://github.com/twbs/bootstrap/blob/master/.editorconfig). For more information, refer to (http://editorconfig.org/).