End

Dart 高效指南 代码风格 文档注释

本文地址

目录

目录

Dart 高效指南 代码风格 文档注释

基本原则

  • 保持一致

当谈论到格式、命名以及参数的相关规则时，哪种规则更好，得出的结论通常是主观且无法达成一致的。但我们知道的是，客观上保持 一致 是非常有益的。

如果两段代码看起来不同，那它们就应该有不同的含义。当一段突出的代码吸引到你的注意时，那它就应该有吸引你的理由。

  • 保持简洁

Dart 会让开发者感到很亲切，因为它继承了许多与 C、Java、JavaScript 及其他语言相同的语句和表达式语法。我们之所以开发 Dart 语言，是因为这些语言依然有很大的改进的空间。我们提供了很多新的特性，比如字符串插值、初始化范式等，以帮助你更简单、更轻松地表达意图。

如果有多种方式来描述一件事情，那么你通常应该选择其中最简洁的方式。这并不意味着你要像 code golf（代码高尔夫挑战赛）一样将所有代码塞到一行中。而是应该让代码变得 简约 而非 密集。

命名风格

UpperCamelCase

  • Classes -- 类名
  • enums -- 枚举类型
  • typedefs -- 类型定义
  • type parameters -- 类型参数
  • extension -- 扩展
class SliderMenu {}
typedef Predicate<T> = bool Function(T value);
extension MyFancyList<T> on List<T> {}

lowercase_with_underscores

  • 库
  • package
  • 文件夹
  • 源文件
file_system.dart
import 'package:js/js.dart' as js;

lowerCamelCase

  • 类成员
  • 顶级定义
  • 变量
  • 参数
  • 命名参数
  • 常量 [推荐]
  • 枚举的值 [推荐]
const pi = 3.14;
const defaultTimeout = 1000;

缩略词和缩写词

  • 缩略词和缩写词要像普通单词一样，仅首字母大写
  • 两个字母的缩写词，比如 ID，与其他常规单词一样，首字母大写即可
    • 例外情况：类似 IO 这样的 缩略词 要全大写
class HttpCon {}  // Http
class DBIOPort {} // DB, IO    
class TVVcr {}    // TV

var httpRequest;  // http
var uiHandler;    // ui
var userId;       // Id
Id id;            // id

其他规则

  • 未使用的回调参数优先使用_、__、___
  • 非私有的标识符不要使用前导下划线 -- 局部变量、参数、局部函数或库前缀，没有私有的概念
  • 不要使用前缀字母
  • 不要显式地命名库，例如 library my_library;

导入导出语句

  • 要把 dart: 导入语句，放到其他导入语句之前
  • 要把 package: 导入语句，放到项目相关导入语句之前
  • 要把 export 导出语句，放到所有导入语句之后
  • 要按 字母顺序 来排序每个部分中的语句

格式化

  • 要使用 dart format 命令格式化你的代码
  • 格式化规则
  • 避免单行超过 80 个字符
    • 考虑缩短局部变量名，或者将表达式抽取为一个新的局部变量
    • 长行文字移动到下一行的开头时，眼睛需要移动更长的距离。这也是为什么报纸和杂志会使用多列样式的文字排版
  • 要对所有流控制结构使用花括号
    • 例外：一个没有 else 的 if 语句，并且这个 if 语句以及它的执行体适合在一行中实现，可以不用括号
dart format .          // 格式化当前目录下所有 Dart 文件
dart format a b/c.dart // 格式化指定目录下，或指定的 Dart 文件

if (arg == null) return;

文档注释

documentation

注释

  • 要像句子一样来格式化注释
    • 首字母要大写，使用句号、叹号或者问号结尾
    • 所有的注释都应该这样：文档注释，单行注释，TODO
  • 不要使用块注释用作解释说明
    • 可以使用块注释来临时的注释掉一段代码，但是其他的所有注释都应该使用 //

文档注释

  • [重点] 要使用 /// 文档注释来注释成员和类型
    • dartdoc 文档注释支持 /// (C# 格式) 和 /** ... */ (JavaDoc 格式)
    • 推荐使用 ///，因为其更加简洁
  • 要让文档注释的第一句从段落中分开
    • 在第一句之后添加一个空行，将其拆分为自己的段落
    • Dartdoc 使用第一段作为类和类成员列表等地方的简短摘要
  • 不要同时为属性的 getter 和 setter 写文档注释
    • dart doc 命令会将 getter 和 setter 作为同一个属性进行处理
    • 如果它们都包含文档注释，dart docs 命令会将 setter 的文档忽略
  • 考虑在文档注释中添加示例代码
    • 人类非常擅长从示例中抽象出实质内容，所以即使提供一行最简单的示例代码，都可以让 API 更易于理解
  • [重点] 要使用方括号在文档注释中引用作用域内的标识符
    • 要链接到特定类的成员，请使用以点号分割的类名和成员名
  • [重点] 要使用平白简单的语句来描述参数、返回值以及异常信息
    • 而不是使用 @param、@returns、@throws 描述参数和返回值
  • 要把文档注释放到注解之前

MarkDown

文档注释中允许使用大多数 markdown 格式，并且 dartdoc 会根据 markdown package 进行解析。

  • 避免过度使用 markdown，内容才是最重要的
  • 避免使用 HTML 来格式化文字
  • 推荐使用三个反引号格式标注代码，而不是每行代码缩进 4 个空格

2023-06-23

posted @ 2023-06-23 20:22  白乾涛  阅读(268)  评论(0)  编辑  收藏  举报