Code Standards - factor1/developer-resources GitHub Wiki

We write code in a consistent style that emphasizes cleanliness and team communication.

Some of our high level guidelines:

• Be consistent.
• Don't violate a guideline without a good reason. (A reason is good when you can convince a teammate)
• Avoid inline comments when possible
• Break long lines after 80 characters
• Delete trailing whitespace
• Don't miszpell
• If you break up a hash, keep the elements on their own lines and closing curly brace on its own line
• A tab indent should be set to two spaces
• Indent continued lines one tab
• Use an empty line between methods
• Use empty lines around multi-line blocks
• Use spaces around operators, except for unary operators, such as !
• Use spaces after commas, after colons and semicolons, around { and before }

• Naming Conventions
• HTML
• CSS
• SCSS
• JavaScript
• PHP

• As of April 2017 we are working towards all projects using BEM naming conventions for HTML/CSS
• Avoid abbreviations
• Avoid object types in names (user_array, email_method CalculatorClass, ReportModule)
• Name variables, methods, and classes to reveal intent
• Treat acronyms as words in names (XmlHttpRequest not XMLHTTPRequest), even if the acronym is the entire name (class Html not class HTML)

• Always use Semantic Markup
• Approach the document with practicality over purity
• Prefer double quotes for attributes.
• Consistency and conventions between team members is paramount.
• Solutions should be as simple and clear as possible.
• Solutions should serve a specific purpose.
• Clever code does not mean good code; readability is critical
• Nested lists MUST NOT be more than 3 levels deep
• HTML attributes should come in this particular order for easier reading of code.

1. id, name
2. class
3. src, for, type, href, value
4. data-*
5. title, alt
6. role, aria-*

• Use soft tabs with two spaces—they’re the only way to guarantee code renders the same in any environment
• When grouping selectors, keep individual selectors to a single line
• Include one space before the opening brace of declaration blocks for legibility
• Place closing braces of declaration blocks on a new line
• Include one space after : for each declaration
• Each declaration should appear on its own line for more accurate error reporting
• End all declarations with a semi-colon. The last declaration’s is optional, but your code is more error prone without it
• Comma-separated property values should include a space after each comma (e.g., box-shadow)
• Don’t include spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values. This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space)
• Do prefix property values or color parameters with a leading zero (e.g., 0.5 instead of .5 and -0.5px instead of -.5px)
• Lowercase all hex values, e.g., #fff. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes
• Use shorthand hex values where available, e.g., #fff instead of #ffffff
• Quote attribute values in selectors, e.g., input[type="text"]. They’re only optional in some cases, and it’s a good practice for consistency
• Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;

• Use the SCSS syntax
• Use hyphens when naming mixins, extends, classes, functions & variables: span-columns not span_columns or spanColumns
• Use one space between property and value: width: 20px not width:20px
• Use a blank line above a selector that has styles
• Avoid using shorthand properties for only one value: background-color: #ff0000;, not background: #ff0000;
• Use one space between selector and {
• Use only lowercase except for string values
• Don’t add a unit specification after 0 values, unless required by a mixin
• Use a leading zero in decimal numbers: 0.5 not .5
• Use space around operands: $variable * 1.5
• Use single colons for pseudo-elements
• Use a % unit for the amount/weight when using Sass’s color functions: darken($color, 20%), not darken($color, 20)

Declarations should be placed in a “logical” manner, with positioning declarations first and similar items grouped:

.home-hero{
  display: block;
  position: relative;
  margin: 0 auto;
  padding: 20px;
  background-color: #eee;
  font: bold 16px/1 $open-sans;
  letter-spacing: 1px;
  color: $white;
}

• Place @extends and @includes at the top of your declaration list
• Place media queries at the bottom of the component stylesheet
• Place concatenated selectors second
• Place pseudo-states and pseudo-elements third
• Place nested elements fourth
• Place nested classes fifth

• Don’t use ID’s for style
• Use meaningful names: $visual-grid-color not $color or $vslgrd-clr
• Use ID and class names that are as short as possible but as long as necessary
• Avoid using the direct descendant selector >
• Avoid nesting more than 3 selectors deep
• Use HTML tags on vague classes that need a qualifier like header.navigation not .navigation.
• Avoid using the HTML tag in the class name: section.news not section.news-section
• Avoid using HTML tags on classes for generic markup like <div>, <span> - .widgets not div.widgets
• Avoid using HTML tags on classes with specific class names like .featured-articles
• Avoid using comma delimited selectors
• Avoid nesting within a media query as much as possible (this can add a lot of bloat)
• Use HTML structure for ordering of selectors. Don’t just put styles at the bottom of the Sass file
• Avoid having files longer than 1000 lines. Use clear and concise sass partials as much as possible

• Use strict equality checks (=== and !==) except when comparing against (null or undefined)
• Use semicolons at the end of each statement (unless writing in Node)
• Prefer single quotes
• Use PascalCase for classes, lowerCamelCase for variables and functions, SCREAMING_SNAKE_CASE for constants, _singleLeadingUnderscore for private variables and functions.
• Prefer template strings over string concatenation
• Prefer array functions like map and forEach over for loops
• Use const for declaring variables that will never be re-assigned, and let otherwise (when writing in ES6)

Example Code:

      // on scroll events
      var globalHeader = $('header.global-nav');
      $(window).scroll(function(){

        if( $(window).scrollTop() > headerHeight ){

          globalHeader
          .removeClass('clear-nav')
          .addClass('white-nav');

        } else if ( $(window).scrollTop() <= headerHeight-headerHeight ) {

          globalHeader
          .addClass('clear-nav')
          .removeClass('white-nav');

        }

      });

• We do not follow the WordPress PHP Standard
• Code must use 2 spaces for indenting (a tab w/ 2 spaces)
• There must not be a hard limit on line length; the soft limit must be 120 characters; lines should be 80 characters or less
• There must be one blank line after the namespace declaration, and there must be one blank line after the block of use declarations
• Closing braces must go on the next line after the body
• Be tidy and well commented