Python 编程规范之代码 (注释) 的引用 (个人向)

设计目标

1. 稳定: 用户根据预设的语法规则应该创建出一条 符合预期的 引用

2. 易用: 此引用语法应该便于书写和理解

3. 明确: 当我使用该引用语法时, 不会产生歧义

4. 普适性: 可以对任意内容, 任意对象进行引用. 它可以是一个函数, 一句代码, 一条注释, 一个非代码文件的指定 part, 一个网页链接等 (查看 此示例)

5. 非侵入式: 对于引用对象来说, 设置锚点不是必须的

   示例:

   侵入式是在被引对象上进行标记, 即被引对象需要被修改:

   请跳转查阅 [表格的第二行内容](#20210403003302).
                                ^---------------^
   规格表:
   
   | 指标 | 数据 |
   | ---- | ---- |
   | A    | 0x0  |
   | B <span id="20210403003302" /> | 0x1 |
       ^--------------------------^
   | C    | 0x2  |
   

   非侵入式的设计, 不必对被引对象进行修改, 只要保证 通过某种规范的引用语法, 在当前上下文环境内, 使引述不具有歧义 即可:

   请跳转查阅 `规格表:rows:#2`.
              ^--------------^
   规格表:
   
   | 指标 | 数据 |
   | ---- | ---- |
   | A    | 0x0  |
   | B    | 0x1  |
   | C    | 0x2  |
   

6. 同步更新: 当被引对象发生变化时 (例如行号, 所处文件, 所属父类等), 与之相关的引用都能得到更新 (或者与变化后的被引对象保持联系)

语法规则与概念解释

什么是模糊引用

当引用的指向不太明确时, 该引用就是模糊引用.

模糊引用是为了便于书写而产生的. 当使用模糊引用时, 您只需要让它具有最小可辨识度即可.

示例:

class AAA:

    def m1(self, name):
        pass

    def m2(self):
        """
        以下引用语法均指向 AAA 类的 m1 方法的 name 参数 (模糊度从低到高):
            see `m1:name`
            see `m1:params:name`
            see `self.m1:name`
            see `self.m1:params:name`
            see `AAA.m1:name`
            see `AAA.m1:params:name`
            see `AAA:func:m1:name`
            see `AAA:func:m1:params:name`
            see `class:AAA:func:m1:params:name`
            see `~/src/main.py:class:AAA:func:m1:params:name`
        """

注意: 模糊引用并不是为了让引用产生歧义, 而是在不产生歧义的原则上尽可能简化引用的表述!

当您发现自己在用的模糊引用已经产生了某种歧义时, 应该适当降低模糊度, 直到模糊程度不再具有歧义为止.

示例:

# a.py

def m1(name):
    pass

class AAA:

    def m1(self, name):
        pass

    def m2(self):
        """
        这时候, 为了引用 AAA 类的 m1 方法的 name 参数, 就不能使用 `m1:name` (因
        为上面有两个 m1), 这时候所能使用最小程度的模糊引用是:
            see `self.m1:name`
        那么如果要引用顶部的 m1 函数的 name 参数, 您应该这样写:
            see `a.py:m1:name`
        或者:
            see `module:m1:name` (这里的 module 是一个内置词, 详见 `章节:内置词
            :清单:module`)
        """

模糊引用的搜索顺序

模糊引用从最近的位置开始找起.

示例:

# a.py
def m1():
    pass

def m2():
    """ see `m1` """
    #   由于 a.py:m1 比 b.py:m1 更近, 所以这里指的
    #   是 a.py 文件中的 m1 函数.

# b.py
def m1():
    pass

内置词

格式说明

通用格式为:

* 全称 (缩写): 描述
    * 子全称 (缩写): 描述

示例:

* functions (func): 指向某个函数
* parameters (params): 指在某个函数/方法的参数中...
    * kwargs: 某关键字参数
* comments (cmt): 指向某条注释

1. 从实用角度考虑, 内置词对单复数的要求并不严格 (虽然在举例时, 我可能更多地展示了复数的形式). 请根据您的用语习惯调整
2. 对于常用的词, 提供了全称和缩写两种形式. 当存在缩写时, 更推荐您去使用缩写

清单

• anchors ([{uid}], [id={uid}]): 示例:

  • 全称

    def f1():
        # [id=scheme_a] use replace ━━━━━━┓
        a = a.replace(..., ...)           ┃
        # [id=scheme_b] use re.sub        ┃
        # # a = re.sub(..., ..., a)       ┃
                                          ┃
    def f2():                             ┃
        """ see `module:f1:cmt:anchors:scheme_a` """
    

  • 缩写 & 模糊引用

    def f1():
        # [scheme_a] use replace ━━━━━━┓
        a = a.replace(..., ...)        ┃
        # [scheme_b] use re.sub        ┃
        # # a = re.sub(..., ..., a)    ┃
                           ┏━━━━━━━━━━━┛
    def f2():              ┃
        """ see `f1:cmt:scheme_a` """
    

• arguments (args): 指函数的参数

  • kwargs: 指可选参数

• attributes (attrs): 指类 (class) 的属性

• class (cls)

• comments (cmt)

  • block_comments (block_cmt)

• each: 常指列表中的某个元素. 示例:

  a = [0, 1, 2, 3]
       ┃
  ...  ┗━━━━━━━━━┓
                 ┃
  # `vars:a:each:#0` starts from zero
  

• functions (func)

• keys: 常用于指向字典中的键. 示例:

  def main(data: dict):
      """
      The `data:keys` are int types.
               ^----^
      """
  

• methods

  • static_methods

• module: 指当前所在的 py 文件

• no{num} (#{num}, {obj}[{num}]): 常用于指向序列中的第几个元素. 示例:

  a = [0, 1, 2, 3]
       ┃
  ...  ┗━━━━━━━━━┓
                 ┃
  # `vars:a:each:#0` starts from zero
  

• package (pkg): 指当前所在的包的路径

• parameters (params)

• project (proj 或 ~/): 指当前的项目路径

• properties (props)

• returns (ret): 示例:

  def f1(path):
      """
      Returns:
          {filepath: filename, ...}
              filepath: str. the prefix is root directory ━┓
              filename: str endswith '.json' ━┓            ┃
      """                                     ┃            ┃
      ...                                     ┃            ┃
                                              ┃            ┃
  def f2(root_dir):                           ┃            ┃
      for path, name in f1(root_dir):         ┃            ┃
          #   path: see `f1:returns:keys` ━━━━╂━━━━━━━━━━━━┛
          #   name: see `f1:returns:values` ━━┛
          ...
  

• variants (vars): 常用于指向某个函数中使用到的变量. 示例:

  def f1():
      a = 1
      b = 2
      c = a + b ━━━━━━━┓
                       ┃
  def f2():            ┃
      """ see `f1:vars:c` """
  

• values: 常用于指向字典中的值

示例

引用任意的内容

def main(name, age):
    """
    Args:
        name: 姓名. 候选人清单由 `~/data/candidates.xlsx:sheets[0]` 提供
                                 ^--------------------------------^ 文件引用
        age: 年龄有效值与 `filter_by_age:params:age_range` 参数有关
                          ^------------------------------^ 源代码引用
    
    References:
        https://example.com  <- 网址引用
    
    Raises:
        ValueError: 请查阅 `filter_by_age:docstring:warnings`
                           ^--------------------------------^ 注释文档引用
    """
    pass

TODO

参考

• https://stackoverflow.com/questions/21289806/link-to-class-method-in-python-docstring