PEP-526与类变量文档字符串是否不兼容？技术咨询

嘿，这个问题我刚好踩过坑，咱们来理清楚到底是怎么回事～

首先直接给结论：PEP-526和类变量的文档说明完全兼容，你遇到的pylint报错，是因为文档字符串的写法不符合规范，和PEP-526本身没关系。

为什么你的代码会报错？ #

看你写的这段代码：

class Joe(object):
    counter: int = 0
    """This is a counter"""

这里的"""This is a counter"""是类体里的一个独立字符串语句，既不属于类的文档字符串（类的文档字符串应该紧跟在class定义行之后），也不属于counter变量的文档——Python本身就没有“给单个类变量加独立文档字符串”的语法，所以pylint会判定这是个无用语句，报pointless-string-statement很合理。

正确给PEP-526类变量加文档的方式 #

根据PEP规范和工具链的支持，有几种推荐的写法：

• 行内注释（最简单直接）
  直接在变量定义行末尾加注释，pylint和其他工具都能识别：

  class Joe(object):
      counter: int = 0  # Tracks the number of operations
  

• 使用typing.Annotated（更正式的元数据绑定）
  如果你想把文档和类型注解绑定在一起，Python 3.9+支持Annotated（旧版本可以通过typing_extensions库兼容）：

  from typing import Annotated
  
  class Joe(object):
      counter: Annotated[int, "This is a counter for tracking actions"] = 0
  

  这种方式的好处是文档信息和类型注解关联紧密，静态检查工具和文档生成工具都能读取到这个元信息。

• 在类的文档字符串中统一说明
  如果变量需要更详细的解释，建议在类的文档字符串里专门列出：

  class Joe(object):
      """A demo class with a counter variable.
  
      Class Variables:
          counter: int - Maintains a running total of completed actions.
          Defaults to 0 when the class is initialized.
      """
      counter: int = 0
  

  这也是PEP-257（文档字符串规范）推荐的做法，适合需要复杂说明的类变量。

补充说明 #

你使用的pylint 1.8.4是2018年的老版本，虽然它已经基本支持PEP-526，但升级到 newer 版本（比如2.x系列）会获得更好的新语法兼容和错误提示。不过核心的文档字符串规则是不会变的——类变量没有单独的文档字符串语法，不能用独立的字符串语句来标注。

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