Dart语言详解

Effective Dart: 设计

下面给出的准则用于指导为库编写一致的、可用的 API。

命名

• 要 使用一致的术语。
• 避免 缩写。
• 推荐 把最具描述性的名词放到最后。
• 考虑 尽量让代码看起来像普通的句子。
• 推荐 使用名词短语来命名不是布尔类型的变量和属性。
• 推荐 使用非命令式动词短语命名布尔类型的变量和属性。
• 考虑 省略命名布尔参数的动词。
• 考虑 为布尔属性或变量取“肯定”含义的名字。
• 推荐 使用命令式动词短语来命名带有副作用的函数或者方法。
• 考虑 使用名词短语或者非命令式动词短语命名返回数据为主要功能的方法或者函数。
• 考虑 使用命令式动词短语命名一个函数或方法，若果你希望它的执行能被重视。
• 避免 在方法命名中使用 get 开头。
• 推荐 使用 to_() 来命名把对象的状态转换到一个新的对象的函数。
• 推荐 使用 as_() 来命名把原来对象转换为另外一种表现形式的函数。
• 避免 在方法或者函数名称中描述参数。
• 要 在命名参数时，遵循现有的助记符约定。

  库

• 推荐 使用私有声明。
• 考虑 声明多个类在一个库中。

  类

• 避免 避免为了使用一个简单的函数而去定义一个单一成员的抽象类
• 避免 定义仅包含静态成员的类。
• 避免 集成一个不期望被集成的类。
• 要 把能够继承的说明添加到文档中，如果这个类可以继承。
• 避免 去实现一个不期望成为接口的类（该类不想作为接口被实现）。
• 要 对支持接口的类在文档注明
• 避免 去 mixin 一个不期望被 mixin 的类
• 要 对支持 mixin 的类在文档注明

  构造函数

• 考虑 在类支持的情况下，指定构造函数为 const。

  成员

• 推荐 指定字段或顶级变量为 final 。
• 要 对概念上是访问的属性使用 getter 方法。
• 要 对概念上是修改的属性使用 setter 方法。
• 不要 在没有对应的 getter 的情况下定义 setter。
• 避免 从返回类型为 bool ， double ， int 或 num 的成员返回 null 。
• 避免 为了书写流畅，而从方法中返回 this 。

  类型

• 推荐 为类型不明显的公共字段和公共顶级变量指定类型注解。
• 考虑 为类型不明显的私有字段和私有顶级变量指定类型注解。
• 避免 为初始化的局部变量添加类型注解。
• 避免 在函数表达式上注解推断的参数类型。
• 避免 在泛型调用中参数类型的冗余使用。
• 要 在 Dart 推断类型错误的时候进行类型注解。
• 推荐 使用 dynamic 注解替换推断失败的情况。
• 推荐 使 function 类型注解的特征更明显
• 不要 为 setter 方法指定返回类型。
• 不要 使用弃用的 typedef 语法。
• 推荐 优先使用内联函数类型，而后是 typedef 。
• 考虑 在参数上使用函数类型语法。
• 要 为类型是任何对象的参数使用 Object 注解，而不是 dynamic 。
• 要 使用 Future 作为无法回值异步成员的返回类型。
• 避免 使用 FutureOr 作为返回类型。

  参数

• 避免 布尔类型的位置参数。
• 避免 在调用者需要省略前面参数的方法中，使用位置可选参数。
• 避免 强制参数去接受一个特定表示”空参数”的值。
• 要 使用开始为闭区间，结束为开区间的半开半闭区间作为接受范围。

  相等

• 要 对重写 == 操作符的类，重写 hashCode 方法。
• 要 让 == 操作符的相等遵守数学规则。
• 避免 为可变类自定义相等。
• 不要 在自定义 == 操作符中检查 null 。