Skip to content

Code

Jump to bottom
Soren edited this page Feb 20, 2018 · 5 revisions

HTML standards

Code

  • We divide our code into big blocks/sections like Header, Featuring, Subscriptions etc. Every big category we’ll comment like this, in our HTML file: <!—HEADER BLOCK, BUILT BY DIANA -->
  • With capslock, must include block name and the name of the developer so as to avoid any mess
  • The class names must be simple and clear, if they contain more than one word, divide the words with -

<div class=”an-example-class”></div>

  • JavaScript files are at the bottom of our HTML file, not in the <head> tag
  • Must not use IDs in HTML code for CSS styles, the only purpose of IDs in the code is for JavaScript and scrolling
  • Must not use inline styles or <style> tag in HTML file. All styles must be in separate files.
  • No scripts in the HTML file, all JavaScript must be in the JS files

SCSS standards

Code

Key Principles

  • Sass should be kept as simple as it can be. Avoid building complex systems unless absolutely necessary.
  • Keep in mind that sometimes KISS (Keep It Simple, Stupid) is better than DRY (Don’t Repeat Yourself).

Syntax & Formatting

  • An indentation is made of two (2) spaces, no tabs.
  • Lines should be, as much as possible, shorter than 80 characters. Feel free to split them into several lines when necessary.
  • CSS should be properly written, possibly following the CSS Guidelines from Harry Roberts.
  • Whitespace is free, use it to separate items, rules and declarations. Do not hesitate to leave empty lines, it never hurts.

STRINGS

  • Declaring the @charset directive on top of the stylesheet is highly recommended.
  • Unless applied as CSS identifiers, strings should be quoted using single quotes. URLs should also be quoted.

NUMBERS

  • Sass makes no distinction between numbers, integers, floats so trailing zeros (0) should be omitted. However, leading zeros (0) help readability and should be added.
  • A zero (0) length should not have a unit.
  • Units manipulation should be thought as arithmetic operations, not string operations.
  • In order to improve readability, top-level calculations should be wrapped in parentheses. Also, complex math operations might be splitted into smaller chunks.
  • Magic numbers dramatically hurt code maintainability and should be avoided at all time. When in doubt, extensively explain the questionable value.

COLORS

  • Colors should be expressed in HSL when possible, then RGB, then hexadecimal (in a lowercase and shortened form). Color keywords should be avoided.
  • Prefer mix(..) instead of darken(..) and lighten(..) when lightening or darkening a color.

LISTS

  • Unless used as a direct mapping to space-separated CSS values, lists should be separated with commas.
  • Wrapping parentheses should also be considered to improve readability.
  • Inlined lists should not have a trailing comma, multi-line lists should have it.

MAPS

  • Maps containing more than a single pair are written on several lines.
  • To help maintainability, the last pair of a map should have a trailing comma.
  • Map keys that happen to be strings should be quoted as any other string.

DECLARATION SORTING

  • The system used for declaration sorting (alphabetical, by type, etc.) doesn’t matter as long as it is consistent.

SELECTOR NESTING

  • Avoid selector nesting when it is not needed (which represents most of the cases).
  • Use selector nesting for pseudo-classes and pseudo-elements.
  • Media queries can also be nested inside their relevant selector.
  • Naming Conventions
  • It is best to stick to CSS naming conventions which are (except a few errors) lowercase and hyphen-delimited.

Commenting

  • CSS is a tricky language; do not hesitate to write very extensive comments about things that look (or are) fishy.
  • For variables, functions, mixins and placeholders establishing a public API, use SassDoc comments.
  • Divide sections using comments such as:
/*********************************************************** example big block
**Diana **/

//**example inner block**//
h1 {
  color: red;
}

Variables

  • Do use the !default flag for any variable part of a public API that can be safely changed.
  • Do not use the !global flag at root level as it might constitue a violation of Sass syntax in the future.

Extend

  • Stick to extending placeholders, not existing CSS selectors.
  • Extend a placeholder as few times as possible in order to avoid side effects.

JavaScript

  • Indentation is with tabs, not spaces
  • Write comments if there is a need for it, but not for self-explanatory code. use them when the code is a mess, function is big, or somehow unreadable Always add a blank line before comments. There should be no code just above a comment.
  • Lines should not extend beyond 80 characters
  • Always add curly braces for if/else/for/while/try, even when the code inside only fills 1 line (Readability issue)
  • if ; marks the end of the statement, it should also mark the end of the line. Few exceptions, ex. for (int i = 0; i < 10; i++) etc.
  • ? and : in a ternary operator must always have space on both side. Do "i > 0 ? true : false", not "i > 0 ?true:false"
  • No filler space in constructs ( do {}, not { } )
  • Always add new line at the end of the code (best practice)
  • Always do type checks when comparing, unless there's a specific reason not to (do ===, not == )
  • jQuery uses double quotes (as far as I have seen)
  • Always use semicolon, even though JS / jQuery has ASI
  • Naming in js / jQuery is camelcase - not with "-" as css.
  • Names should be descriptive, but not extreme. Keep it as short as possible
Clone this wiki locally