dart-effective-style

Dart 代码风格

目录

• 命名约定
• 指令排序
• 格式规则
• 工作流

命名约定

严格遵循以下命名约定，以保持 Dart 生态系统的一致性。

• 类型： 类、枚举类型、typedef、扩展和类型参数使用 UpperCamelCase 命名。
• 变量和成员： 类成员、顶层定义、变量、参数和命名参数使用 lowerCamelCase 命名。
• 常量： 常量变量（包括枚举值）优先使用 lowerCamelCase。
  • 特殊情况： 如果正在编辑使用 SCREAMING_CAPS 的现有代码，或处理生成的代码（例如 protobuf），则保持现有风格一致。
• 文件和目录： 包、目录和源文件使用 lowercase_with_underscores 命名。
• 导入前缀： 导入前缀使用 lowercase_with_underscores 命名。
• 缩略词： 超过两个字母的缩略词和缩写按普通单词的形式大写（例如 Http、Uri）。两个字母的缩略词全部大写（例如 ID、UI）。如果缩写位于 lowerCamelCase 标识符的开头，则全部使用小写（例如 httpConnection）。
• 私有性： 成员和顶层声明使用前导下划线 _ 表示库级私有。局部变量、参数、局部函数或库前缀不要使用前导下划线。
• 未使用的参数： 对未使用的回调参数，优先使用通配符（_、__ 等）明确表示其用途。
• 前缀： 不要使用字母前缀（例如匈牙利命名法中的 kDefaultTimeout）。
• 库： 不要显式命名库（例如，避免使用 library my_library;）。

示例

// GOOD
class SliderMenu {}
typedef Predicate<T> = bool Function(T value);
const defaultTimeout = 1000;
var httpConnection = connect();

futureOfVoid.then((_) {
  print('Operation complete.');
});

// BAD
class slider_menu {}
const DEFAULT_TIMEOUT = 1000;
var HTTPConnection = connect();
const kDefaultTimeout = 1000;

指令排序

严格按以下顺序组织文件序言。各部分之间用空行分隔，并在每个部分内按字母顺序排列指令。

1. 首先放置 dart: 导入。
2. 其次放置 package: 导入。
3. 第三放置相对导入。
   • 最佳实践： 对于同一包 lib 目录中的文件，优先使用相对导入。
4. 将 export 指令单独放在所有导入之后。

示例

// GOOD
import 'dart:async';
import 'dart:collection';

import 'package:bar/bar.dart';
import 'package:foo/foo.dart';

import 'src/util.dart';

export 'src/error.dart';

格式规则

• 必须遵守的格式要求： 提交任何代码前，必须运行 dart format。Dart 官方的空白字符处理规则完全以 dart format 的输出为准。
• 行长度： 行长优先控制在 80 个字符以内。如果 dart format 因行长度限制产生难以阅读的输出，请重组深层嵌套表达式或提取变量。
• 流程控制： 所有流程控制语句都使用花括号，以避免悬空 else 问题。
  • 例外： 如果不带 else 子句的 if 语句可以完整写在一行内，则可以省略花括号。

示例

// GOOD
if (isWeekDay) {
  print('Bike to work!');
} else {
  print('Go dancing or read a book!');
}

if (arg == null) return defaultValue;

// BAD
if (overflowChars != other.overflowChars)
  return overflowChars < other.overflowChars;

工作流

提交前格式化和代码检查工作流

在最终确定任何 Dart 代码修改前执行此工作流，以确保符合风格要求。

• 任务进度
  • 1. 根据命名约定检查代码（例如，类型使用 UpperCamelCase，变量使用 lowerCamelCase）。
  • 2. 验证导入顺序（dart: -> package: -> 相对导入 -> 导出）。
  • 3. 对修改过的文件运行 dart format .。
  • 4. 运行 dart analyze，检查静态分析和代码检查错误。
  • 5. 运行 validator -> 检查错误 -> 修复分析器报告的问题。