CODING.md

Coding Conventions and Guidelines

• Project Structure
• Coding Rules

Project Structure

All component modules are defined in:

 -- /src
    -- /components
       -- /<component folder>

          -- <component>.js
          -- <component>.spec.js
          -- <component>.scss
          -- <component>-theme.scss

          -- /demo<name>

             -- index.html
             -- style.css
             -- script.js

All component modules are compiled and distributed individually to:

 -- /dist
    -- /modules
       -- /js
          -- /core
          -- /<component folder>

Additionally, all component modules are compiled and deployed as a library to:

 -- /dist
    -- angular.material.js
    -- angular.material.css

NOTE: the dist directory is not version controlled.

Coding Rules

Coding conventions:

The best guidance is a coding approach that implements both code and comments in a clear, understandable, concise, and DRY fashion.

Below is a sample code that demonstrates some of our rules and conventions:

/**
 * @ngdoc module
 * @name material.components.slider
 */
angular.module('material.components.slider', [
  'material.core'
])
  .directive('mdSlider', SliderDirective);

/**
 * @ngdoc directive
 * @name mdSlider
 * @module material.components.slider
 * @restrict E
 * @description
 * The `<md-slider>` component allows the user to choose from a range of values.
 *
 * It has two modes: 'normal' mode, where the user slides between a wide range of values, and
 * 'discrete' mode, where the user slides between only a few select values.
 *
 * To enable discrete mode, add the `md-discrete` attribute to a slider, and use the `step`
 * attribute to change the distance between values the user is allowed to pick.
 *
 * @usage
 * <h4>Normal Mode</h4>
 * <hljs lang="html">
 *   <md-slider ng-model="myValue"
 *              min="5"
 *              max="500">
 *   </md-slider>
 * </hljs>
 *
 * <h4>Discrete Mode</h4>
 * <hljs lang="html">
 *   <md-slider md-discrete
 *              ng-model="myDiscreteValue"
 *              step="10"
 *              min="10"
 *              max="130">
 *   </md-slider>
 * </hljs>
 *
 * @param {boolean=} mdDiscrete Whether to enable discrete mode.
 * @param {number=} step The distance between values the user is allowed to pick. Default 1.
 * @param {number=} min The minimum value the user is allowed to pick. Default 0.
 * @param {number=} max The maximum value the user is allowed to pick. Default 100.
 */
function SliderDirective($mdTheming) {
  //...
}

• With the exceptions listed in this document, follow the rules contained in Google's JavaScript Style Guide.
• All components must have unique, understandable module names; prefixed with 'material.components.'.
• All components must depend upon the 'material.core' module.
• Do not use $inject to annotate arguments.
  ngAnnotate is used as part of the build process to automatically create the annotations.
• All public API methods must be documented with ngdoc, an extended version of jsdoc (we added support for markdown and templating via @ngdoc tag). To see how we document our APIs, please check out the existing ngdocs and see this wiki page.
• All directives must use the md- prefix for both the directive name and any directive attributes.
  Directive templates should be defined inline.

Testing

• All components must have valid, passing unit tests.
• All features or bug fixes must be tested by one or more specs.

Coding

• Wrap all code at 100 characters.
• Do not use tabs. Use two (2) spaces to represent a tab or indent.
• Constructors are PascalCase, closures and variables are lowerCamelCase.
• When enhancing or fixing existing code
  • Do not reformat the author's code
  • Conform to standards and practices used within that code; unless overridden by best practices or patterns.
  • Provide jsDocs for functions and single-line comments for code blocks
  • Be careful of regression errors introduce by your changes
  • Always test your changes with unit tests and manual user testing.

Patterns

• All source files will be automatically wrapped inside an anonymous closure using the Module Pattern.

• Use the Revealing Pattern as a coding style.

• Do not use the global variable namespace, export our API explicitly via AngularJS DI.

• Instead of complex inheritance hierarchies, use simple objects.

• Avoid prototypal inheritance unless warranted by performance or other considerations.

• We love functions and closures and, whenever possible, prefer them over objects.
  

  Do not use anonymous functions. All closures should be named.

Documentation

• All non-trivial functions should have a jsdoc description.
• To write concise code that can be better minified, we use aliases internally that map to the external API.
• Use of argument type annotations for private internal APIs is not encouraged, unless it's an internal API that is used throughout AngularJS Material.