Dart学习之注释

一、前言

注释是给代码做解释说明，意在记录当时的思路，让他人看得懂你的代码，也避免出现自己看不懂自己代码的现象。

在 Dart 中，注释不仅仅是“写给别人看的文字”，它也是我们管理代码、整理思路、辅助协作的一种方式。尤其是在学习阶段，好的注释能让我们更快回忆起代码当时为什么这样写。

二、一句话理解

Dart 注释就是写给开发者看的说明文字，编译器会忽略它，但读代码的人会依赖它理解代码意图。

三、注释类型

Dart 中常见的注释包括单行注释、多行注释、文档注释、元数据注释和待办事项标记。

3.1 单行注释

Dart 中单行注释使用 // 实现，常用于对一行代码或一个小代码块做解释说明。

记忆方法：两个 / 表示这一行从这里开始进入注释。

void main() {
  // 单行注释
  int a = 5;
}

3.2 多行注释

Dart 中多行注释使用 /* */ 实现，常用于临时注释多行代码，或者解释一段较长逻辑。

记忆方法：/* 表示注释开始，*/ 表示注释结束。

void main() {
  /*
   * 多行注释
   * int a = 5;
   * int b = 3;
   */
}

3.3 文档注释

Dart 中文档注释使用 /// 或 /** */，主要用于类、属性、函数、参数、顶级变量等说明。

文档注释和普通注释不同，它更像是代码的正式说明书。

/// 定义一个打印文本的函数
void text(String value) {
  print(value);
}

3.4 元数据注释

Dart 中元数据注释以 @ 开始，用于为声明附加额外信息，常见的有 @override 和 @deprecated。

@override
String toString() {
  return 'Dart comment example';
}

3.5 标记待办事项

Dart 中常用 // TODO: 标记等待处理的事项，方便后续继续补充或优化。

// TODO: 后续补充异常处理逻辑

四、注释作用

优雅的注释可以很好地记录思路、便于协作和管理代码。

• 记录思路：帮助我们回忆当时为什么这样写。
• 便于协作：让别人更快理解我们的代码。
• 代码管理：提高代码可读性和可维护性。

五、注释风格

好注释事半功倍，坏注释事倍功半。

写注释时建议注意三点：

• 清晰简洁：避免冗余和模糊描述。
• 适度注释：不要给显而易见的代码强行加注释。
• 保持更新：代码变了，注释也要跟着变。

六、总结

Dart 中常见注释包括单行注释、多行注释、文档注释、元数据注释和待办事项标记。

真正好的注释，不是把代码翻译一遍，而是解释代码背后的意图。写注释时要做到清晰、适度、及时更新，让注释真正帮助我们理解和维护代码。