前言

编写代码，实质是在梳理逻辑，为了完善整个逻辑流程，我们借用编程语言的变量、函数、流程控制、循环、注释、方法等串接起来，完善一套系统的逻辑。

为了完善这套逻辑，我们借助了许多工具：设计方法、架构设计、项目组织等。
意识到没有，代码的好坏一定程度上可以从逻辑层面评判。

• 符合逻辑，不一定是最优的代码
• 不符合逻辑，一定不是好的代码

逻辑的串接靠的是编程语言的变量、函数、流程控制、循环、注释等。

一、 规范

绝大多数的人，不会从零完整的完成一个复杂的项目，大多是团队共同合作，完成一个大的项目。

这个时候，假如你是中途参与进来。你在实现逻辑的时候，你是照着自己的逻辑来还是依照团队的风格来。

比如项目组织，命名等...

按照团队的命名风格来

1.1 编程语言的规范

每门编程语言，都存在一定的规范，比如 Python 采用的下划线的变量命令规则，Go 则采用驼峰式的变量命令规则等。
Effective Dart: 代码风格
Kotlin 编码规范

另外，Dart语言默认80个字符换行，在团队中需要设置100个字符换行。

二、 命名

给变量，函数，方法命名时易于理解

• 专业的单词：使用领域内的单词
• 避免空泛的名字
• 具体的名字
• 变量名带上更多细节
• 不使用令人误解的名字
• 布尔值命名

2.1 领域内单词

天星银行的领域单词分为几大类

类型	不常见的单词
account(账户)	biometric(生物识别)、faceID（面容识别）、touchID(指纹识别)
deposit(存款)	timeDeposit(定期)、currentDeposit (活期)、
kyc(开户)	employment(职业) 、questionnaire（调查问卷）、liveness(活体检测)、document(证件)
loan(贷款)	anti frau(反欺诈)、partial repay（部分还款）、credit(信用)
personal(个人)	language(语言)、fileMaintain(资料维护)、promotion(促销)
security(安全)	softToken(安全令牌)、remain(提醒)
transfer(转账)	fps(转数快)、tupta(分享)、

2.2 避免空泛的名字

变量的命名一般要赋予一定的意义，极少情况下可以使用没有什么意义的单词。比如最常见的：

var i int

for (i=0;i<10;i++){
    fmt.Println(i)
}

这种没什么意义的单词，一般适用于局部作用域。

2.3 具体的名字

完成什么任务就使用什么单词。一般变量使用名词居多，函数使用动词开头居多。

String toString() => json.encode(toJson());
 /// 设备硬件支持的生物识别类型 (指纹，面容)
static Future<BiometricType> hardwareDetectedBiometric() async {} 

int pages = 0;
String userName = "";

2.4 带上更多细节

一般命名不建议过长，也不建议过短，最长三个单词的长度吧

如何带上更多的细节。

• 尝试使用后缀
• 尝试使用单位
• 尝试指向具体的细节

比如：

String currentFlowName;

VoidCallback onFinishLoad,

List<OtpType> otpTypes;

final BiometricType openedBiometricType;

几组对仗的后缀：

• max/min
• first/last
• begin/end
  ...

ServerCanStart() 不如 CanListenOnPort()

2.5 不使用令人误解的词

比如：Filter 在数据库操作中容易使用这个单词，这个单词没有带上更多的细节，实质上在使用的过程中，还是需要查看编写的SQL 语句等才能知道具体的过滤细节。整体思考多了几步。不易让人理解。

建议多读几遍自己命名的单词

2.6 布尔值

提到布尔值，因为就存在两种结果。所有，一般使用是否这样意思的词。

通常使用 is,has,can,should这样的词，可以把布尔值变得更明确。

final bool canBack;
final bool backOnFinish;

// 是否有更多收支历史
@JsonKey(name: 'hasMoreRecord', required: true)
final bool hasMoreRecord;

2.7 不建议使用的单词

get、read、util 恰恰这几个单词，在写代码中最容易使用。选择替代方案。

单词	更多选择
send	deliver（传送）、dispatch（派遣）、announce（宣布）、distribute（分配）、route（路线）
find	search（搜寻）、extract（提取）、locate（位于）、recover（恢复）
make	launch（发动）、create（创建）、begin（开始）、open（打开）
start	create、set up（建立）、build（建立）、generate（发送）、compose（构成）、add（添加）、new（新）

2.8 带单位的值

static const int resultTimeoutInSecs = 10;

• 使用专用的单词 - 例如：不用 Get ，使用 Fetch、Download 。由上下文决定
• 避免使用空泛的单词 - tmp 和 retval 。除非有特定的理由

3 设计

好的源代码应当“看上去养眼”。如何使用好的留白，对齐及顺序来让你的代码变得更易读。

• 使用一致的布局，让读者很快习惯这种风格
• 让相似的代码看上去相似
• 把相关的代码分组，形成代码块

这里以设计的四个规范类比代码的组织。

3.1 对齐

编程语言为什么强调缩进？难道不是为了阅读代码的人更容易看懂代码吗？写代码的人更容易组织代码吗？仅仅是设计者为了好玩？

static Future<void> start(FlutterDriverWrapper driver) async {
    driver.log('register test begin...');

    /// home page
    await driver.waitFor(KeyManager.homeBtnLogin);
    await driver.takeScreenshot();
    await driver.tap(KeyManager.homeBtnLogin);

    /// login page
    await driver.waitFor(KeyManager.loginBtnRegister);
    await driver.takeScreenshot();
    await driver.tap(KeyManager.loginBtnRegister);

    /// validate new username page
    await driver.enterText(KeyManager.validateNewUsernameInputUsername, TestConfig.username);
    await driver.takeScreenshot();
    await driver.tap(KeyManager.validateNewUsernameBtnNext);
」

• 放眼望去，确实知道实现什么任务
• 风格统一
• 整整齐齐

3.2 重复、亲密、比较、审美

最应该避免的其实就是写重复的代码，一般的做法往往是提炼，将重复的抽象出一个函数之类的。这里的重复，是风格的统一。

• 重复的代码使用方法去提炼
• 选择一个有意义的顺序，始终一致地使用它
• 把声明按照块组织起来

  static double get s1 => s(3);

   /// Loan pages
  static const String loanCreditPrepare = '/loanCreditPrepare';
  ...

  /// Coupon
  static const String couponList = '/couponList';
   ...

  /// Transfer pages
  static const String transferPrepare = '/transferPrepare';
   ...
}

可以结合比较下 student.go 和 teacher.go

这样的组织方式，讲道理，并不太会给阅读代码的人带来太多的认知负担。

3.3 留白

设计领域页面的设计，并不强调内容越多越好，恰当的在页面上留有空白，使整体设计有呼吸感。

那编程如何实现留白？

• 恰当的换行，使相似的内容更紧凑
• 提取，使用方法来组织不规范的东西
• 代码分段

假如你一个函数需要写 100 多行，不好意思，我可能建议你，不要这么做。

• 拆分，逻辑梳理、提取方法
• 尽量维持最长 30～50行左右（这样使屏幕能装载下，一次就能完成的阅读整个函数的逻辑）

static Future<void> start(FlutterDriverWrapper driver) async {
    driver.log('kyc test begin...');

    /// home page
    await driver.tap(KeyManager.notifyBtnOk);

    /// prepare page
    await driver.tap(KeyManager.bottomBtnRight);

    /// kyc terms page
    await driver.delayed(TestConfig.pageStartDelay);
    await driver.scrollIntoView(KeyManager.bottomBtnRight);
    await driver.tap(KeyManager.bottomBtnRight);
    ...

4 注释

帮助阅读代码的人对代码了解的和写代码的人一样多

4.1 什么时候不需要注释

• 好的命名不需要注释

4.2 什么时候需要注释

• 关键点
• 缺陷点
• 常量
• 全局注释
• 总结性注释

关键点：
有些时候，仅仅靠之前的“表面工作” 已经不能完全能够满足让人易于理解。这个时候需要在关键点添加注释。

缺陷点：
是的，承认自己的代码写的不是最优的，仅仅只是实现，还存在更优的办法，所以需要在有缺点的地方加上注释。

  // TODO: move to remote config
  static const String customerServicePhoneNumber = '9288321';

  /// TODO: 更好的方案是：现有的图形上做动画，而不是重置动画。
  @override
  void didUpdateWidget(TotalAssetsWidget oldWidget) {
    super.didUpdateWidget(oldWidget);
    ...
  }

常量：
给常量注释，赋予了更多的意义。

  ///
  /// Area codes
  ///
  static const String areaCodeHK = '852';

全局注释：
一般在文件开头，表明文件内代码完成的任务。

class TestConfig {
  TestConfig._();
  ///
  /// Environment variables are used to configure the tests.
  /// It's more convenient to modify the env than to change the code.
  ///
  /// They are just key value pairs like following:
  ///
  /// ------------------------------
  ///   username = "bob010"
  ///   password = "bob0100"
  ///
  ///   accountGroup = "login"
  ///   kycGroup = "login, kyc"
  /// ------------------------------
  ///
  /// Note: line 'accountGroup = "login"' means which tests should be run
  /// for [accountGroup] test group.
  ///
  static void loadEnv() {
    load();
    env.removeWhere((k, v) => Platform.environment.containsKey(k));
    env.forEach((k, v) => log('[ENV] $k = $v'));
  }

5 流程控制

5.1 条件参数的顺序

涉及流程控制的话，一般涉及条件判断，条件判断语句中的参数的顺序。

if (number < 10) {} // A

if (10 > number) {} // B

if (receivedNumber < expectedNumber) // C

if (expectNumber > receivedNumber) // D

通常我们会选择 A，C，
那么应该准从什么样的尊则？

左边倾向于变量，右边倾向于常量；

5.2 if...else 语句块的顺序

可以参照下面的下面准则：

• 先判断正向逻辑的，再判断负向逻辑
• 先处理简单
• 先处理有趣的或者可疑的

  void _listenScrollPosition() {
    if (widget.bottomButtonText == null) return;
    ...
  }

5.2 避免使用三目运算符

三目运算符一定程度上能够精简代码，减少代码的行数，但是却存在另外一个缺点，即：不容易理解（虽然大学教材总会考这类题目，判断执行的顺序和结果）

只在简单场景下使用三目运算符。

5.4 函数什么时候返回

经常我们编写函数的时候，喜欢声明一个变量用来存储结果，到所有的逻辑结束后返回这个变量作为函数的返回值。

• 可以提前进行函数返回值，多几个 return, 没关系
• 最好函数都要有返回值，Golang 里建议至少返回一个 错误信息

5.5 减少多层级的嵌套

层级的增多，增加了认知的负担。而且容易出现不容易发现的 bug。

如何减少嵌套：

• 提前函数返回
• 在循坏内使用 continue

5.6 表达式

建议使用短表达式

if createParam.Data.ShopType == RegionEntrances {}
// 感觉表达式长了，怎么做：

var shopTypeEqual = createParam.Data.ShopType == RegionEntrances

if shopTypeEqual {}

6. 重新组织代码，持续迭代

有下面几条准则：

不相干的任务，提取出来
一次只专注干一件事
梳理逻辑时，如果你能使用自然语言表述出来，对你写出逻辑清晰的代码很有帮助
单函数行数不宜过长 30 ～ 50 为佳。再一个评判方法是，查看函数的内容无需滚动鼠标进行翻页。
少些代码：每写一行都需要维护；不需要的功能，砍掉，不需要的代码，删掉

---