About Best Practices

Best coding practices are a set of informal rules that the software development community has learned over time which can help improve the quality of software. The best practices put forth are are to be the standard bearers for coding techniques when re-using or extending the TWCBC codebase.


The Golden Rule

All code in any part of the code base should look like a single person typed it, no matter how many people contributed.


HTML
  • Human Readable

    Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.

  • HTML5 doctype

    Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.

  • Syntax
    • Use soft-tabs with two spaces
    • Nested elements should be indented once (2 spaces)
    • Don't include a trailing slash in self-closing elements
  • Attributes
    • Attributes should be lowercase.
    • Always use double quotes ("), never single quotes.
    • Boolean attributes should be used without quoted values to avoid redundancy.
  • Attribute order

    HTML attributes should come in this particular order for easier reading of code.

    • id
    • class
    • data-*
    • for | type | href | src
  • HTML Comments
    • Section comments are separated from the previous block by two lines, and should have one following line of space.
    • Prepend section headings with an equal sign (=), to make a Find operation easier.

CSS
    Syntax Rules
    • Use soft-tabs with two spaces
    • When grouping selectors, keep individual selectors to a single line
    • Include one space before the opening brace of declaration blocks
    • Place closing braces of declaration blocks on a new line
    • Include one space after : in each property
    • Each declaration should appear on its own line
    • End all declarations with a semi-colon
    • Comma-separated values should include a space after each comma
    • Don't include spaces after commas in RGB or RGBa colors
    • Do not specify units for zero values, e.g., margin: 0; instead of margin: 0px;
    • Lowercase all hex values, e.g., #fff instead of #FFF
    • Use shorthand hex values where available, e.g., #fff instead of #ffffff
    • Quote attribute values in selectors, e.g., input[type="text"]
    • Use a new line for every block, list or table element, and indent every such child element to show heirarchy and improve understanding
    • Avoid Qualifying ID and class names with type selectors
    • ID's are bad for CSS, only use ID's for javascript hooks when necessary
  • Declaration Organization
    1. Box (Display, Float, Position, Left, Top, Width, Height, Margin, Padding, etc.)
    2. Border
    3. Background
    4. Text
    5. Other
  • Hexidecimal Notation
  • For color values that permit, 3 character hexadecimal is preferred

  • !important
    Just don't do it.

    Use greater specificity to workaround using !important; -- you will be judged in the afterlife

  • Use the SMACSS Approach

    SMACSS stands for Scalable and Modular Architecture for CSS and it has 2 core goals.

    Much like OCCSS, the purpose of this categorization is less code repetition, a more consistent experience, and easier maintenance. Under SMACSS there are 5 general categories of css rules.

    • Base — These are your defaults (html, body, h1, ul, etc)
    • Layout — These divide the page into major sections
    • Module — These are the reusable modular components of a design
    • State — These describe how things look when in a particular state (hidden or expanded, active/inactive)
    • Theme — These define things like a color scheme or typographic treatment across a site
    .componentName {
      Base {
        ...
      }
    
      Layout {
        ...
      }
    
      Module {
        ...
      }
    
      State {
        ...
      }
    
      Theme {
        ...
      }
    }
    

Sass/SCSS

Sass (or SCSS) is the preferred method of CSS pre-processing used in any Time Warner Cable project. An extension of CSS that adds power and elegance to the basic language. It allows to use variables, nested rules, mixins, inline imports, and more.

As a general rule, you will never want to alter a file with a .css extension as this is the output file. Always refactor .scss files.

The recommended way to compile your Sass code is through node-sass (rather than Ruby Sass). This allows eliminating the dependency on Ruby for projects that don't already require it and is the fastest method of compiling Sass.

Learn more about Sass
  • File Organization
    • Mixins and variables go in scss/global/.
    • Styles related to components/modules/views go in sass/components/.
    • Sass and CSS from other projects goes in sass/vendor/.
  • Main Stylesheet

    All files get compiled into the main.scss stylesheet, and should be scoped accordingly.

    The main.scss file serves as a "table of contents" and the @import directives should be listed with vendor dependencies first, then author dependencies and core stylesheets, then components.

    Organize the components imports in a manner that makes sense, in other words, group components with the component they extend or inherit from.

  • Structuring Code

    @extends and @includes are likely to be overwritten by future elements, placing them at the top of the property list calls them out and avoids the beginning of a specificity war.

    • @extends should be grouped together at the top of the selector.
    • @includes should be grouped together after @extends.
    • Regular styles for the current selector should be after @includes.
    • Nested selectors appear last.
    • Nested selectors using & should appear above child (>) nested selectors.
  • Limit nesting to 3 levels and/or 50 lines

    Nesting selectors more than three levels deep and the code is at risk of being to reliant on HTML structure, overly-specific and difficult to understand.

    50 lines is reasonable length for keeping an entire block on a code editor screen without having to scroll.

  • Variablize ALL THE THINGS!
    • Variablize all colors.
    • Numbers (other than 0 or 100%) with strong meaning or frequent use should be variables.
    • Use hyphens (-) in variable names.
    • Name variables based on what they represent, not their values, e.g. $text-size-large instead of $text-size-24.
    • Colors, fonts, and base measurements are all great candidates for variables. If you find yourself writing a number other than 0 or 100% more than once, make it a variable.
    • Most variables should be stored in the _variables.scss partial; however, it's acceptable to define component specific variables in the component files.
    • In this case, the variables should be stored at the top of the file.
  • Commenting Code
  • Try to stick with standard CSS comments, but you can use the Sass style (//) comments for trivial comments or quickly debugging.

    // File headers are commented thusly:
    
    /* ======================================================================
    Component Name -- Version: 1.0.0.0 - Updated: MM/DD/YYYY
    ====================================================================== */
    
    /*
    * Chunk of long
    * text gets commented
    * like this
    */
    
    // Hints get styled like this:
    /* Hint */
    

Javascript
  • Prefix all javascript-based selectors with js-. The idea is that you should be able to tell a presentational class from a functional class. Most of the codebase doesn't do this, let's try and move toward it.


SEO
Only One h1 Tag Per Page

While technically we could load a page up with h1 tags, it's a bad SEO practice and can cause penalties.


Use Title Attributes with Links

Using a title attribute in your anchor elements will improve accessibility when used the right way.

It is important to understand that the title attribute should be used to increase the meaning of the anchor tag.


How Much Will A Reader Read?

"A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts."

The main Element

The <main> element should contain the main content for your web page. All of this content should be unique to the individual page, and should not appear elsewhere on the site. Any content that is repeated on multiple pages (logos, search boxes, footer links, etc.) should not be placed within the <main> element.

Use the ARIA role=”main” attribute here is it indicates the significance of this element to programs that don’t yet support the <main> element (such as some screen readers).

You should only use one <main> element on a page, and it shouldn’t be placed within an <article>, <aside>, <header>, <footer>, or <nav> element.

The section Element

The <section> element is used to represent a group of related content. This is similar to the purpose of an <article> element with the main difference being that the content within a <section> element doesn’t necessarily need to make sense out of the context of the page.

It’s advisable to use a heading element (<h1><h6>) to define the topic for the section.

Using this blog post as an example, you could have <section> elements that represent each of the individual parts within the post.

If you just need to group content together for styling purposes you should use a <div> element rather than a <section>.

The article Element

The <article> element should contain a piece of self-contained content that could be distributed outside the context of the page. This includes things like news articles, blog posts, or user comments.

You can nest <article> elements within one another. In this case it’s implied that the nested elements are related to the outer <article> element.

The aside Element

The <aside> element is used to represent content that is tangibly related to the content surrounding it, but could be considered separate. This includes things like sidebars (like those you might find in a book), groups of <nav> elements, figures and pull quotes.

The header Element

The <header> element is used to represent the introductory content to an article or web page. This will usually contain a heading element as well as some metadata that’s relevant to the content, such as the post date of a news article for example. It could also contain a table of contents (within a <nav> element) for a longer document.

A <header> element will be associated with the nearest sectioning element, usually it’s direct parent in the page structure.

The footer Element

The <footer> element is used to represent information about a section such as the author, copyright information, or links to related web pages.

As with <header>, the <footer> element is associated with the nearest sectioning element.