YAML – 注释

YAML - 注释

注释（Comments）对于注解（annotating）您的 YAML 文件至关重要，它们能让文件对您自己和他人来说更容易理解。YAML 支持单行注释（single-line comments）。

语法

YAML 中的注释以井号（#）开头，并持续到行尾。井号（#）之后在该行上的任何内容都会被 YAML 解析器（parser）忽略。

# This is a single-line comment.

注释可以单独出现在一行，也可以出现在包含 YAML 数据的行的末尾，前提是它们与数据通过空格分隔开：

key: value # This comment describes the key-value pair.

# This comment is on its own line, perhaps explaining the block below.
another_key: another_value

YAML 不支持多行块注释（multi-line block comments）（像某些语言中的 /* ... */）。要创建多行注释，只需在每行开头都加上一个 #：

# This
# is a multi-line
# comment block.

注释的主要特点

解析时被忽略：在处理 YAML 文件时，被注释掉的部分会完全被跳过。
增强可读性：注释有助于阐明数据的目的、配置设置或复杂结构。
位置：注释不能出现在未引用的纯标量（unquoted plain scalars）内部。如果 # 出现在纯标量内部，它会被视为字符串的一部分。
在纯标量中，# 不需要转义：在未引用的多行纯标量中，# 字符通常会终止标量，或者如果它不在行首以表示注释的方式出现，则会被解释为内容。对于需要字面包含 # 且可能存在歧义的情况，请使用引用的标量（quoted scalars）。
在引用的标量（"..." 或 '...'）内部，# 符号被视为字面字符（literal character），而不是注释分隔符（comment delimiter）。

在集合内部的注释

您可以在序列（列表）和映射（字典）内部放置注释，以解释特定的项或段落：

servers:
  - ip: 192.168.1.100 # Main application server
    role: app
  - ip: 192.168.1.101 # Database server
    role: db
# - ip: 192.168.1.102 # Temporarily disabled web server
#   role: web

config:
  timeout: 30 # Timeout in seconds
  retries: 3  # Number of retries for failed connections

注释掉代码块

大多数现代文本编辑器和 IDEs（集成开发环境，如 VS Code、IntelliJ IDEA、Sublime Text 等）提供了快捷键来注释或取消注释选定的 YAML 代码行或块。常用的快捷键是 Ctrl+/ (Windows/Linux) 或 Cmd+/ (macOS)。这通常会在选定行的开头加上 #。

此功能对于暂时禁用 YAML 文件中的某些部分以便进行测试或调试（testing or debugging purposes）非常有用。

注释的最佳实践

保持清晰简洁。
如果数据本身不够清楚，解释“为什么”这样做，而不仅仅是“是什么”。
随着 YAML 数据的变化，及时更新注释。
使用注释标记段落、解释复杂配置或记录待办事项（TODOs）。