node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »

embedit.framework.ui

Main Embedit Application

Coding Conventions and Guidelines

Project Structure

All component modules are defined in:

 -- /src
    -- /components
       -- /<component folder>
          -- <component>.js          
          -- <component>.less
          -- <component>.html
 -- /test
    -- /components
       -- /<component folder>
          -- <component>Spec.js          

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:

(function( angular, window, undefined ) {
 
  'use strict';
  
  /**
   * @ngdoc module
   * @name embedit.framework.ui.slider
   */
  angular.module( 'embedit.framework.ui.slider', [
    'embedit.framework.ui.core'
  ])
    .directive( 'emSlider', emSlider );
  
  /**
   * @ngdoc directive
   * @name emSlider
   * @module embedit.framework.ui.slider
   * @restrict E
   * @description
   * The `<em-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 `em-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">
   *   <em-slider ng-model="myValue"
   *              min="5"
   *              max="500">
   *   </em-slider>
   * </hljs>
   *
   * <h4>Discrete Mode</h4>
   * <hljs lang="html">
   *   <em-slider md-discrete
   *              ng-model="myDiscreteValue"
   *              step="10"
   *              min="10"
   *              max="130">
   *   </em-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 10.
   */
   
  function emSlider( emCoreSvc ) {
    //... 
  }
 
})( window.angular, window );
  • All components must have unique, understandable module names; prefixed with 'embedit.framework.ui.'.
  • All components must/can depend upon the 'embedit.framework.ui.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. To see how we document our APIs, please check out the existing ngdocs and see this wiki page.
  • All directives must use the em- prefix for both the directive name and any directive attributes.
    Directive templates should be defined in external html file.

Testing

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

Coding

  • Use jscs with settings applied from existing jscs.json
  • Use jshint with settings applied from existing .jshintrc
  • Use *editorconfig with settings applied from existing .editorconfig
  • Use provided IDE settings ( also some live templates macros included )
  • Wrap all code at 120 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 components should be wrapped in 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 Angular 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.

i18n

  • Always register static strings to api/i18n/:langCode file and use it in templates via translate filter or directive

Detailed Guidelines

After you read and applied above recommendations to codebase please follow these guides: