Code style guidelines - GothamSass/chrysler GitHub Wiki

A consistent coding style helps make code easier to read and maintain. Many of these SCSSRules are a matter of opinionated preference and common practices from the front-end community. An alternate choice would serve equally well, but follow them anyway for the sake of consistency within this codebase

The ultimate goal is to have our whole codebase look like the same person wrote it. Coding style matters because code is a communication tool between developers, with its grammar and set of rules as in any written language. If not enforced, the code is difficult to read, and developers might not understand the intent behind the code, leading to bad refactoring and more code smells. It may result into a snowball effect, rushing towards doom and destruction. http://www.theguardian.com/info/developer-blog/2014/may/13/improving-sass-code-quality-on-theguardiancom

Naming

Functions, mixins, and variables should be declared with all lowercase letters and hyphens instead of underscores. Exceptions made for outside vendor libraries, such as Compass or Bourbon.

Classes

@TODO Team needs to finalize our flavor of ice cream

No IDs

Data attributes or js-namespaced classes are preferred and should be considered before resorting to an ID. IDs should only be used when absolutely needed by JavaScript, form elements, or WAI-ARIA roles.

JS Hooks

When we need to bind markup use a JS specific class namespaced with .js-. Never use a CSS styling class as a JS hook. Conversely, never apply styles to a JS hook.

State Rules

State rules describe how our patterns will look with in a particular state, e.g. Is it hidden or expanded? Is it with or without errors? State classes are namespaced with .is- or .has-.

Comments

Code comments should not be used excessively; they require maintenance just as code (an out-of-date comment is often far worse than no comment at all). Comments should add information or context or rationale to the code, not simply restate what the code is doing. Comments should be concise.

@TODO Harry Roberts has some great guidelines related to comments. Also add documentation about Sass-Doc

Line length

Limit all lines to a maximum of 80 characters.

Property Sort Order

Write @extend statements first, followed by mixins (@include), properties sorted in alphabetical order and nested properties.

CSS property sort order follows best practices declared by Mdo's Code Style.

.declaration-order {

  /* Extend/Inheritances & Mixins*/
  @extend my-extend;
  @include my-mixin();

  /* 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;
}

Checkout CSS Architecture Example here.

Quotes

Use single quotes ' '. URLs should always be enclosed within quotes.

Shorthand

Prefer the shortest shorthand form possible for properties that support it.

Vendor libraries

3rd party plugins that provide their own SCSS file should be placed in sass/vendor. These files are excluded from the linter.

Whitespace

  • Use two-space indents. No tabs.
  • Split selectors onto separate lines after each comma.
  • Insert a space after comma separated items in a list.
  • Parentheses should not be padded with spaces.
  • Opening braces should be preceded by a single space.
  • Properties should be formatted with a single space separating the colon from the property's value.
  • Separate block, rule, function, and mixin declarations with empty lines. Use empty lines to visually and logically group variable definitions.

Editor Configuration

If you are using Sublime Text, make sure your preferences contains the following:

"default_line_ending": "unix",
"ensure_newline_at_eof_on_save": true,
"tab_size": 2,
"translate_tabs_to_spaces": true,
"trim_trailing_white_space_on_save": true

In addition, the following packages are highly recommended:

@TODO list packages

@TODO add quote from Paul Irish about why why it is important to care about your editor/tools