读 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
  - ...

（完）