风格指南

统一用语

指导原则中，使用以下词汇，来指明推荐程度

• 坚持：总应该遵循约定。只有遇到及其不寻常的情况，才能打破原则
• 考虑：通常应该遵循约定。如果熟悉约定背后的考虑，有更好的理由违背，可以修改，但请保持一致；
• 避免：绝对不应该做的事情
• 原因：约定或原则背后的考虑

程序结构(Application structure)

总体考虑原则

• 坚持有一个短期实施方案，也要考虑长期方案；
• 不要直接复制代码；
• 要考虑写第一步以后，后面接下来需要怎么处理；

LIFT

代码组织，必须考虑结构化，遵循一下原则：

• Locate：方便快速定位(locate)代码。
  1. 相关文件聚合在一起；
  2. 具有描述性的目录结构，方便定位代码；
• Identify：一眼识别(identify)代码。
  1. 文件名具有良好的说明性；
  2. 一个文件，只含一个组件；
  3. 如果有简短、紧密相关的代码，允许聚合在一个文件中；
• Flattest：尽量保持扁平结构(flattest)。
  1. 尽可能保持扁平； 原因：层级很深的时候，查找文件不便。
  2. 同一个目录，文件超过7个的时候，考虑创建子目录。 原因：心理学研究，事物超过9个，比较吃力。
• 遵循DRY（Do Not Repeat Yourself，不重复自己）原则。必须坚持DRY，但不能过度DRY，以致于牺牲可读性。比如：xxx.component.jsx，因jsx已经表明这是个react组件。必要的时候，也可以写上component后缀。不过通常来说，这个例子不恰当，React组件用大写驼峰即可。

原因：

• 提高开发效率；目的是方便维护，快速定位到代码；
• 写代码的时候，可以问自己：能否快速打开，与此特性相关的所有文件，并立即开展工作

文件结构约定(File structure conventions)

单一职责原则(SRP)

所有文件，都应该遵循单一职责原则。

• 坚持每个文件只定义一样东西；
• 考虑文件限制在400行以内；

原因：

• 文件中代码功能单一，更容易阅读、维护，也减少版本控制系统的成本，如git等，团队修改代码时候的冲突；
• 防止隐藏的缺陷，如多个逻辑在一个文件时候，容易有变量共享、依赖直接产生意外耦合等问题；
• 更容易实现按需加载； 主要可以让代码更可复用、更易阅读，减少出错

命名

总体命名原则

坚持所有代码，使用一致的命名规则。坚持遵循同一个模式类描述文件的特性和类型。推荐模式feature.type.ts

原因：

• 一致的命名约定，方便用一致的搜索方式查找内容
• 一致的目录和文件名，能更好清楚的表达命名的意图；

使用点和横杆来分割文件名

• 坚持在描述性命名中，用横杠风格单词；
• 坚持使用点分割描述性名字和类型；
• 坚持遵循先描述组件特性，在描述类型的模式，对所有组件用一致的命名规，推荐模式feature.type.ts；
• 坚持用习惯后缀来描述类型，如：.service, .component, .module

考虑：

• 类型名字能提供一致的识别文件方式
• 类型名可以方便IDE模糊搜索特定文件类型
• 为自动化提供您模式匹配

引导(Bootstrapping)

• 坚持把项目的入口，引导程序，以及平台相关逻辑，放到main.ts中；
• 坚持在引导逻辑中，包含错误处理代码
• 避免把应用逻辑放main中

考虑：

• 启动逻辑，应该一致，遵循约定
• 其他技术平台，也遵循这一约定

服务名(service name)

• 坚持为服务的类型名加上Service后缀，如：DataService
• 有些命名，明显是服务，则以-er结尾。如果日志服务可以命名为Logger，比LoggerService更好。

类(class)

• 坚持用大写驼峰命名
• 大写驼峰命名，来标识，可以构造的东西

常量(constants)

• 坚持用const声明常量
• 常量可以考虑用独立的目录，如const，统一存放

参考文档

• AngularJS风格指南