Main Embedit Application

Coding Conventions and Guidelines

• Project Structure
• Coding Rules
• Detailed guidelines
• Typescript

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:

• ArchitectureGuide.md - Application architecture.

• Installation Guide - How to run locally our devstack

• Git Commit Styleguide - Git Commits style Guide

• EmbedIT esStyleguide - EmbedIT ECMAScript style guide

• EmbedIT ngStyleguide - EmbedIT angularJS style guide

• EmbedIT Code Review guide - EmbedIT Code Review guide

• HomecreditAppStructure.md - Homecredit Specific Application Structure

• Hints - Hints for creating components via Java annotations

• Troubleshoot.md - Common issues