讀 Angular 代碼風格指南

讀 Angular 代碼風格指南

本文寫於 2021 年 1 月 17 日

原文地址：Angular 文檔

該文章擁有完整的代碼風格指南——大到如何編排文件夾，小到如何進行變量命名都涉及。可是與 ng 略有綁定，因此這裏整理一下能夠單獨拿出來的通用部分。

單一職責

請堅持每一個文件只定義同樣東西（例如服務或組件），而且把文件大小限制在 400 行代碼之內。

小文件一般很是容易閱讀、維護，並能防止在版本控制系統裏與團隊衝突。

小文件還能夠防止一些隱蔽的程序缺陷，當把多個組件合寫在同一個文件中時，可能形成共享變量、建立意外的閉包，或者與依賴之間產生意外耦合等狀況。

總的來講，單一職責原則可讓代碼更加可複用、更容易閱讀，減小出錯的可能性。

若是該文件是一個函數，那麼請堅持定義簡單函數，而且限制在 75 行以內。

這樣能更便於咱們作單元測試。

命名

命名是一件很是重要的事情，他可讓其餘人看咱們的代碼，或者是咱們本身在一段時間以後再看以前的代碼時，能夠迅速理解文件內容、變量含義、方法用途……。也能夠在全局搜索的時候，讓咱們能夠迅速定位到目標。

代碼給人讀的時間比給機器讀的時間多多了，所以咱們須要慎重考慮命名。

能夠遵循如下兩個原則：

1. 堅持使用一致的命名規則；
2. 堅持遵循同一個模式來描述特性和類型。

文件命名

ng 推薦使用點和橫槓來分隔文件名——在描述性名字中，用橫槓來分隔單詞；用點來分隔描述性名字和類型。

具體來講，就是先描述組件特性，再描述它的類型的模式，而且對全部組件使用一致的類型命名規則！！！

也就是 feature.type.ts，例如 hero.service.ts, app.module.ts, home.component.html, global.style.css。

經常使用的後綴有 *.service、*.component、*.pipe、.module、.directive。若是有必要，能夠建立更多類型名，但必須注意，不要建立太多了。

這樣命名文件可讓咱們來快速的識別文件中有什麼，而且輕鬆的利用編輯器或者 IDE 的模糊搜索功能找到特定文件類型。或是爲自動化任務提供模式匹配。

文件名與符號名

若是將將文件命名爲 hero.service.ts，那麼符號名，即類/變量名，應該命名爲 HeroService。

若爲 todo-list.service.ts，則該命名爲 TodoListService。

也就是說，使用大寫駝峯命名法來命名類，而且須要匹配符號名與它所在的文件名，在符號名後面追加約定的類型後綴（例如 Component、Service）。

單元測試文件名

應該與測試的文件保持一致，xxx.xx.ts 的單元測試文件名應該叫作 xxx.xx.spec.ts。

結構組織與 LIFT 原則

咱們應該力求項目結構組織符合 LIFT 原則：

• Locate 快速定位代碼
• Identify 一眼識別代碼
• Flattest 儘可能保持扁平結構
• Try Do Not Repeat Yourself 嘗試遵循不重複本身的原則

上述四項原則重要程度從大到小。

爲什麼？

LIFT 提供了一致的結構，它具備擴展性強、模塊化的特性，它讓咱們能夠快速鎖定代碼，提升開發的效率。

另外，檢查應用結構是否合理的方法是問問本身：「我能快速打開與此特性有關的全部文件並開始工做嗎？」

Locate（定位）

堅持直觀、簡單和快速地定位代碼。

要想高效的工做，就必須能迅速找到文件，特別是當不知道（或不記得）文件名時——把相關的文件一塊兒放在一個直觀的位置能夠節省大量的時間。

而且富有描述性的目錄結構會讓你和後面的維護者眼前一亮！！！

可使用上面說的，使用 特性 + 後綴 + 文件類型 的命名方式來方便咱們的定位

Identify（識別）

文件的名字請達到這個程度：看到名字馬上知道它包含了什麼，表明了什麼。

文件名要具備說明性。保證文件名精準的方法就是：確保文件中只包含一個組件。

避免建立包含多個組件、服務或者混合體的文件。

爲什麼？

花費更少的時間來查找和琢磨代碼，就會變得更有效率。較長的文件名遠勝於較短卻容易混淆的縮寫名。

Flattest（扁平）

請堅持儘量保持扁平的目錄結構。

考慮當同一目錄下達到 7 個或更多個文件時建立子目錄。

考慮配置 IDE，以隱藏無關的文件，例如生成出來的 .js 文件和 .js.map 文件等。

沒人想要在超過七層的目錄中查找文件！！！

扁平的結構有利於搜索。

另外一方面，心理學家們相信，當關注的事物超過 9 個時，人類就會開始感到吃力。因此，當一個文件夾中的文件有 10 個或更多個文件時，可能就是建立子目錄的時候了。

仍是根據你本身的溫馨度而定吧。除非建立新文件夾能有顯著的價值，不然儘可能使用扁平結構。

Try Do Not Repeat Yourself (T-DRY)

堅持 DRY（Don't Repeat Yourself，不重複本身）。

避免過分 DRY，以至犧牲了閱讀性。

雖然 DRY 很重要，但若是要以犧牲 LIFT 的其它原則爲代價，那就不值得了。這也就是爲何它被稱爲 「Try」-DRY。

推薦的目錄結構

堅持把全部源代碼都放到名爲 src 的目錄裏。

堅持若是組件具備多個伴生文件 (.ts、.html、.css 和 .spec)，就爲它建立一個文件夾。

我習慣使用的前端目錄結構：

- src
  - app
    - moduleA // 模塊 B
      - assets
      - components
      - ...
    - moduleB // 模塊 A
    - shared // 共享模塊
  - layouts
  - assets
  - main.ts
  - ...

（完）