减少认知复杂度 (Mental Complexity) 概述

用户在使用你的库之前, 需要快速并准确的对库的函数和抽象建立一个认知模型. 实现这个目标的最好方式, 是减少他们遇到的认知复杂度.

减少认知复杂度的方法包括:

• 简单性: 要尽量使用最少的组件实现提供最多功能的 API, 重用已有的 Kotlin 类型和结构, 避免冗余. 尽可能, 创建一小群核心抽象, 并以此为基础构建更多功能.

• 可读性: 用宣言的风格来编写 API, 使得代码的意图清晰易懂. 直接从问题域中选择抽象的名称, 除非绝对有必要, 否则不要使用新的名称. 基本数据类型只用于它们本来应该的使用意图. 清楚的区分核心功能和可选功能.

• 一致性: 为你的 API 的每个设计方面保持单一, 清晰的方案. 使用统一的命名约定, 错误处理方式, 以及模式, 无论是面向对象的模式, 还是函数式模式.

• 可预测性: 设计你的库要遵循 "最小惊讶原则(principle of least surprise)". 确保默认设置符合最常见的使用场景, 让用户能够通过最简单最少量的代码完成他们的任务. 只允许通过明确指定的方式来扩展你的库, 以维持一致性和可预测性.

• 可调试性: 确保你的库能够便利的抽取信息和追溯函数的嵌套调用, 帮助用户解决故障. 抛出异常时, 异常的类型和内容应该与底层的错误相匹配, 提供所有必须的细节信息, 帮助用户高效的诊断和解决问题. 应该能够捕捉并输出问题域对象的状态, 并查看它们的任何中间表达.

• 可测试性: 确保你的库, 以及使用它的代码, 能够容易的进行测试.

关于如何在 Kotlin 中实现这些方法, 后续的章节包含更多详细信息.