JS 编码规范 命名规范

本文内容参考了《阿里Java开发手册(嵩山版)》

业务代码 所有命名采用字母打头
不使用 _ 和 $ 开头避免与系统和第三库的变量混淆

命名表意清晰不要胡乱缩写，避免不可读甚至歧义

在子父类的成员变量之间、或者同一模块下不同代码块的局部变量之间避免采用完全相同的命名
这样可以提高代码的可理解度，避免混淆

命名规范

变量命名

采用小驼峰的命名方式
当是ID等特殊单词（通常较短其往往同时大小写统一）时，所有字母都大写

• 全局变量可在命名中体现，如g、global词缀等
• 常量使用全大写，下划线分词命名
  各语言普遍采取的方式

表达数据类型/结构的单词定位于固定位置，如最前方或最后方
若使用了设计模式可在命名中体现出来，帮助理解代码

会被重复使用的常量值，必须定义常量
避免在重复使用时，误输错输导致出错

函数命名

采用小驼峰的命名方式

类命名

采用大驼峰命名方式
系统对象类型也是大驼峰，通过 new 实列化，结构上可以保持统一

文件名

使用小写文件名
为避免有些服务器大小写敏感，有些不敏感

文本文件编码方式 UTF-8

代码格式

花括号

左花括号 左侧不换行右侧换行；
右花括号 左、右侧都换行，除非 右侧是 else

xxx {
  ···
} else {
  ···
}
// 空代码块 简写 {}

缩进

• 采用2空格代替tab进行代码缩进
  制表符tab在不同编译器的解释不尽相同
  2空格相较4空格层级看起来会更简短一点，降低横向滚动的可能性

空格

括号内侧相邻字符无空格
括号左外侧 需空格
同方向括号之间无空格

双目、三目运算符两侧应有空格

逗号之后应有空格

冒号后应有空格

最后一个键值对后不要写逗号（Internet Explorer 8 会崩溃，JSON会报错）

双斜线//注释后，添加空格

行字符限制

常见120个，根据实际情况确定，主要提高阅读的便捷性
换行的原则：

1. 在第一次换行时要进行缩进；
   用来与同级其他代码区分
2. 运算符与下文一起换行；
3. 方法调用的点符号与下文一起换行；
4. 多个参数需要换行时，在逗号后进行；

相关的符号一同换行，避免代码误读

分号

语句是否以分号结尾，见仁见智

大多数情况下，单行语句可以不写编译通过
以下情况会出问题（当然你可以避免）：
如果一条语句以“（”、“[”、“/”、“+”、或“-”开始，那么它极有可能和前一条语句合在一起解释。
好文链接

编码要求

一个方法行数做出限制，如80行(有效代码)
内部逻辑整合抽离出去，能够快速了解方法，方便项目交接

不同逻辑块间 可插入空行隔开，提升可读性

不要在其他表达式中插入赋值语句。赋值语句不清晰不利于代码理解。

必须初始化变量

使用===进行比较

除非你希望 自动类型转化，才使用==

switch

• 每个 case 要么通过 continue/break/return 等来终止。
  原因就是switch的判断机制
• 必须包含一个 default 语句并且放在最后。
  保留兜底类似于异常捕获的思想，保证各个分支方向都有明确的出口

if/else/for/while/do 语句中必须使用大括号

虽然支持单行语句直接直接匹配，但后面增加时很容易忘记补上大括号从而造成bug

不要在条件判断中直接放入其它复杂的语句

增加理解成本，可以将语句结果赋值给变量，再放入条件判断

代码设计

• 系统设计阶段，共性业务或公共行为抽取出来公共模块、公共配置、公共类、公共方
  法等，在系统中不出现重复代码的情况，即 DRY 原则（Don’t Repeat Yourself）

• 需求分析与系统设计在考虑主干功能的同时，需要充分评估异常流程与业务边界。

• 存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。
  说明：有缺陷的底层数据结构容易导致系统风险上升，可扩展性下降，重构成本也会因历史数据迁移和系
  统平滑过渡而陡然增加，所以，存储方案和数据结构需要认真地进行设计和评审，生产环境提交执行后，
  需要进行 double check。
  正例：评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发
  展、表或字段之间的辩证关系、字段名称、字段类型、索引等；数据结构变更（如在原有表中新增字段）
  也需要进行评审通过后上线。

系统架构设计时明确以下目标：

• 确定系统边界。确定系统在技术层面上的做与不做。
• 确定系统内模块之间的关系。确定模块之间的依赖关系及模块的宏观输入与输出。
• 确定指导后续设计与演化的原则。使后续的子系统或模块设计在一个既定的框架内和技术方向上继
  续演化。
• 确定非功能性需求。非功能性需求是指安全性、可用性、可扩展性等

注释

参考jsdoc的语法

---

有意义的命名

• 命名尽量简洁明了，不应该重复上下文已经明确的信息
  简单理解：场景下如果只涉及到张三，就没必要强调张三的某某一个道理

针对固定的情景使用特定的词汇：

1. 标识状态的变量，可用is can has need等助动词开头
2. 数值量的命名 首选有意义的简短命名，如 width length count，如果没有合适的就采用 number**Of**xxx xxxCount 之类的通用命名
3. 类名应用名词
4. 字典(Map)的命名 应当能表现映射关系 推荐使用 values**By**Key 的方式，如 usersByID。
5. 函数或方法名 尽量采用动词或判断性词汇
   常用的动词有get set read create add update reset delete remove等

函数方法 使用判断性词汇 应注意与 标识状态的变量 所用词汇区分开。