如何让Black Python代码格式化工具对齐字段多行注释

Black作为零配置的Python代码格式化工具，原生不开放细粒度的注释排版自定义规则，默认会将行尾注释的续行对齐到当前代码块的缩进起始位置，不会保留手动调整的纵向对齐效果，这是工具本身的设计定位决定的，没有内置配置项可以直接修改这个行为。

可直接实现多行尾注对齐的方案 #

• 利用Black原生的格式化跳过标记
  Black原生支持# fmt: off/# fmt: on标记，标记包裹的代码段会跳过格式化，完全保留手动排版的效果：

  @dataclass
  # fmt: off
  class Thing1:
      property1: int                    # The first property.
      property2: typing.List[int]       # This is the second property
                                        # and the comment crosses multiple lines.
  # fmt: on
  

  这种方案不需要安装额外依赖，缺点是标记段内的所有代码都不会被Black格式化，需要手动保证代码风格符合项目规范。
• 增加格式化后处理步骤
  可以在执行Black格式化之后，增加一步注释对齐后处理：扫描所有带行尾注释的代码行，将后续连续的同缩进层级的独立注释行，对齐到上一行行尾注释的起始列。处理后的效果完全符合预期——同一字段对应的多行注释保持纵向对齐，且不会影响Black对其他代码的格式化逻辑，也不需要手动给代码加特殊标记，可以全项目自动执行。

兼顾Black规范与可读性的最佳实践 #

如果不想引入额外处理流程，推荐使用Black原生支持的注释写法，从根源上避免排版错位问题：

• 多行长注释统一放在对应字段的上方作为块注释
  这是Black官方推荐的长注释写法，格式化后不会出现排版错位，注释和字段的对应关系清晰：

  @dataclass
  class Thing1:
      # The first property.
      property1: int
      # This is the second property
      # and the comment crosses multiple lines.
      property2: typing.List[int]
  

• 短注释保留行尾写法，长度超过单行限制的注释拆分到字段上方
  这种写法兼顾了短注释的紧凑性和长注释的排版一致性，格式化后不会被破坏：

  @dataclass
  class Thing1:
      property1: int  # The first property.
      # This is the second property
      # and the comment crosses multiple lines.
      property2: typing.List[int]
  

• 多个字段的共性说明、字段的复杂业务逻辑说明，统一写到类的docstring中，既避免重复写多行尾注，也方便后续统一维护。

内容的提问来源于stack exchange，提问作者paxdiablo