AngularJS Style

基本認知

• 一定要寫 comments，越詳細越好 ( JSDoc )
• 需使用 JSCS 跟 JSLint 檢查語法

Include JS

• angular.js 使用 google cdn 去宣告

  <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.3.xx/angular.min.js"></script>

• angular.js 需支援 ie8 的關係，請使用 1.3 (含)以上的版本

• 若要使用 angular.js plugin library (ex: ui-router)，請 fork 到 PIXNET 並使用 bower 宣告

Directory Structure of a Module (sample)

• 盡量每個檔案都只做一件事情，除非 service 互相是有相依性的。

  相依性是指 directive 跟 directive 的 controller
  或 children directive 需要的 parent directive。

• 一個 module 內分類：先依類型，再依功能

   ├── app
   │   ├── app.js
   │   ├── controllers
   │   │   ├── MainCtrl.js
   │   │   ├── home
   │   │   │   ├── FirstCtrl.js
   │   │   │   └── SecondCtrl.js
   │   │   └── about
   │   │       └── ThirdCtrl.js
   │   ├── directives
   │   │   ├── home
   │   │   │   └── directive1.js
   │   │   └── about
   │   │       ├── directive2.js
   │   │       └── directive3.js
   │   ├── filters
   │   │   ├── CommonFilter.js
   │   │   ├── home
   │   │   │   └── homeFilter.js
   │   │   └── about
   │   │       └── aboutFilter.js
   │   ├── factories
   │   │   ├── CommonFactory.js
   │   │   ├── app
   │   │   │   ├── App1Factory.js
   │   │   │   └── App2Factory.js
   │   │   └── user
   │   │       ├── User1Factory.js
   │   │       └── User2Factory.js
   │   └── services
   │       ├── CommonService.js
   │       ├── cache
   │       │   ├── Cache1Service.js
   │       │   └── Cache2Service.js
   │       └── models
   │           ├── Model1Service.js
   │           └── Model2Service.js
   ├── templates
   │   ├── home
   │   │   └── header.html
   │   └── about
   │       └── aside.html
   └── test
  

Naming

• module name - 小駝峰

  e.g. angular.module('pixTestApp')

• controller name - 大駝峰並且以 Ctrl 結尾

  e.g. 'angular.module('pixTestApp').controller('MainCtrl', function() { … });'

• directive name - 必須是小駝峰，
  不然 framework 無法辨識，前方需要有 PIXNET 的 prefix - pix

  e.g. `angular.module('pixTestApp').directive('pixPreventDefault', function() { … });

• filter name - 小駝峰

  e.g. angular.module('pixTestApp').filter('showApproximateInstalledCount', function() { … });

• factory name
  當做是 factory 或 service: 大駝峰並且以 Factory 結尾
  當做是儲存資料的 factory：大駝峰並且以 Info 結尾

  e.g. angular.module('pixTestApp').factory('FrontModuleFactory', function() { … });

• service name - 大駝峰並且以 Service 結尾

  e.g. angular.module('pixTestApp').factory('ApplicationService', function() { … });

• router name - 小駝峰+複數

  e.g. $stateProvider.state('articles', {...});

• resolve function name - 小駝峰，並以 Data 結尾

  e.g.

  var myResolveFunction = {
    'accountData': function () {
      // get my account here ....
      return data;
    }
  };
  

• constant name - 全部大寫英文，並且用 underline 隔開 '''

e.g. ARTICLE_ARTICLE_OPEN: 'open';

Template

• 在 html template 順序: html origin attribute > angular's attribute

  <div class="myClass" ng-class="{'active'}" ng-click="Ctrl.myFunc()"></div>

• angular attribute 把有關連的放在同在一起。

  <!-- active 跟 interval 是屬於 my-directive 的屬性，應該放在一起 -->
  <div class="myClass" my-directive active="true" interval="-1" ng-class="{'active'}" ng-click="Ctrl.myFunc()"></div>

Expression

• 左右要空一格 e.g. {{ something | filter }}

Directives

• Restrict to Element and Attributes

  • 假如專案沒有需要處理 ie8，directive 在畫面上就可以用 element 樣式呈現
  • Element(E): 類型是 web component
  • Attributes(A): 類型是比較像 plugin, 可以壘加效果多個 direcitve 效果。

• 只在 directive 做 DOM 的操作

  更精簡就是在 directive 的 controller 中做邏輯判斷，然後在 link function 做 DOM 的操作。

DI Annotations

• 雖然有 ngmin ，但是早期版本曾經發生過 directive 的 controller 沒改到的例外，
  所以後來統一都寫 ngmin 後的寫法避免 minify 爛掉推到 production site

  e.g.

  angular.module('whatever').controller('MyCtrl', function ($scope, $http) { ... });

  要寫成

  angular.module('whatever').controller('MyCtrl', ['$scope', '$http', function ($scope, $http) { ... }]);

• 一行超過 120 字元時要折行變成

  angular.module('whatever')
  .controller('MyCtrl', [
     '$scope',
     '$http',
  function ($scope, $http) { ... }]);

  先是放 angular 原生的 service，最後才是自身 module 的 Service

  angular.module('myApp')
  .controller('MyCtrl', [
     '$scope',
     '$http',
     'MyService',
     'Helper'
  function ($scope, $http, MyService, Helper) { ... }]);

$ Wrapper Services

使用 $timeout 跟 $interval 取代 setTimeout 跟 setInterval
因為 Angular 特別在另外 sync data binding。

使用 $timeout 跟 $interval 記得在結束要清除，以免造成 memory leak

$scope.$on('$destroy', function() {
  // Make sure that the interval nis destroyed too
  $interval.cancel(countDown);
});

$ 效能

當在 $timeout 裡面的變數沒有變更時，記得在 $timeout 設置第三個參數為 false 避免 $digest 循環 當不需要支援 IE8，請使用 Angular 1.3 以上版本。 請務必當變數沒有變更的時候綁上 one-time binding。Angular 1.3 以上使用原生的 one-time binding (前贅::)，或是使用 bindonce 套件。

---

ref:

• angularjs-style-guide
• JohnPapa Style Guide