Coding standards help write more consistent code across a project or team.
Use these standards as-is, or fork them and modify them to your liking.
Copy these standards to your project's repository as coding-standards.md for all project contributors to reference. Utilize and customize the supplied EditorConfig and linter files based upon these guidelines.
Let these standards grow and change as your project grows and changes.
- Principles
- HTML
- CSS / SCSS
- Naming & Abbreviation Patterns
- File & Folder Organization
- Editor Helpers & Preferences
- EditorConfig
- Linters (scss-lint)
Write readable, understandable, consistent code appropriate to the product and team.
Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.
- Use a consistent indent style. (Default: Spaces)
- Use a consistent indent size. (Default: 2)
- Use double or single quotes consistently (Default: Double)
- Indent nested elements.
- Close all tags, even when optional.
- e.g.
</li>or</body>
- e.g.
- Don't include a trailing slash in self-closing elements.
- e.g.
<img src="img/src.png">
- e.g.
- Use end-of comments after the closing tag of a multi-line code block.
- e.g.,
</div> <!-- eo .class-name -->
- e.g.,
Example:
<!DOCTYPE html>
<html>
<head>
<title>Page title</title>
</head>
<body>
<img src="images/company-logo.png" alt="Company">
<h1 class="hello-world">Hello, world!</h1>
<div class="mod">
<div class="mod-item mod-item-1">
Fun!
</div><!-- eo .mod-item-1 -->
</div><!-- eo .mod -->
</body>
</html>Write HTML attributes in a consistent order. Classes should be first.
classid,namedata-*src,for,type,href,valuetitle,altaria-*,role
Example:
<a class="..." id="..." data-toggle="modal" href="#">
Example link
</a>
<input class="form-control" type="text">
<img src="..." alt="...">- Use a consistent indent style. (Default: Spaces)
- Use a consistent indent size. (Default: 2)
- Use one discrete selector per line in multi-selector rulesets.
- Include a single space before the opening brace of a ruleset.
- Include one declaration per line in a declaration block.
- Use one level of indentation for each declaration.
- Include a single space after the colon of a declaration.
- Use lowercase and shorthand hex values.
- e.g.,
#fffand#bada55, not#ffffffand#BADA55
- e.g.,
- Use double quotes consistently.
*e.g.,
content: " "; - Quote attribute values in selectors.
- e.g.,
input[type="checkbox"]
- e.g.,
- Prefix property values with a leading zero.
- e.g.,
0.5px, not.5px
- e.g.,
- Where allowed, avoid specifying units for zero-values, e.g., margin: 0.
- e.g.,
margin: 0, notmargin: 0px
- e.g.,
- Include a space after each comma in comma-separated property or function values.
- Include a semi-colon at the end of the last declaration in a declaration block.
- Place the closing brace of a ruleset in the same column as the first character of the ruleset.
- Separate each ruleset by a blank line.
Example:
.selector-one,
.selector-two {
background-image: url("img/background-image.png");
color: #bada55;
}
.selector-three[type="checkbox"] {
letter-spacing: 0.5px;
margin: 0;
}Declarations are to be consistently ordered based on a simple principle:
- Positioning
- Display & Box Model
- Typography
- Everything Else
.selector {
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
margin: 10px;
padding: 10px;
border: 10px solid #333;
font-family: sans-serif;
font-size: 16px;
text-align: right;
color: #fff;
background: #000;
}Avoid unnecessary nesting. Just because you can nest, doesn't mean you always should.
- At most, aim for no more than two levels of specificity.
- Nest psuedo-classes and media queries at the end of the declaration block, separated from other properties by an empty line.
Comment your code to describe components, how they work, their limitations, and the way they are constructed.
- Place comments on a new line above subject.
- Use comments to break code into discrete sections.
- Use a simple, consistent comment style.
Example:
/* ==========================================================================
Section comment block
========================================================================== */
/* Sub-section comment block
========================================================================== */
/**
* Short description using Doxygen-style comment format
*
* The first sentence of the long description starts here and continues on this
* line for a while finally concluding here at the end of this paragraph.
*
* The long description is ideal for more detailed explanations and
* documentation. It can include example HTML, URLs, or any other information
* that is deemed necessary or useful.
*
* @tag This is a tag named 'tag'
*
* TODO: This is a todo statement that describes an atomic task to be completed
* at a later date. It wraps after 80 characters and following lines are
* indented by 2 spaces.
*/
// Basic comment- Place
@extendstatements on the first line of a declaration block. - Place
@includestatements at a sensible position in a relevant group of rulesets.
.box-red {
@extend .box;
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
@include size(100px);
display: inline-block;
overflow: hidden;
box-sizing: border-box;
margin: 10px;
padding: 10px;
border: 10px solid #333;
}Use Autoprefixer to post-process your CSS with the necessary vendor prefixes.
| Namespace | Meaning |
|---|---|
l-[layout] |
layout |
t-[theme] |
theme or trump |
u-[utility] |
utility |
is-[state] |
states (commonly JS-based) |
js-[selector] |
for JS selectors |
| Abbreviation | Meaning |
|---|---|
art |
image, illustration, etc. |
bd |
body |
btn |
button |
btm |
bottom |
content |
content |
deck |
deckhead or subhead |
ftr |
footer |
h |
headline or heading |
hdr |
header |
hgroup |
headline group |
horiz |
horizontal |
img |
image |
item |
item |
lg |
large |
list |
list |
md |
medium |
meta |
meta description |
mod |
module |
nav |
navigation |
pg |
page |
sm |
small |
top |
top |
trigger |
a dropdown trigger, for example |
txt |
text |
tz |
tease |
vert |
vertical |
xl |
extra large |
xs |
extra small |