其他分享
首页 > 其他分享> > 如何正确遵守 Python 代码规范

如何正确遵守 Python 代码规范

作者:互联网

命名约定

  1. 函数名,变量名和文件名应该是描述性的,尽量避免缩写,除了计数器和迭代器、作为 try/except 中异常声明的 e 以及作为 with 语句中文件句柄的 f.
  2. 用单下划线(_)开头表示变量或函数是 protected 的,不应该被外部访问(除了子类).

注释

函数和方法

一个函数必须要有文档字符串, 除非它满足以下条件:

  1. 外部不可见
  2. 非常短小
  3. 简单明了

文档字符串应该包含函数做什么,以及输入和输出的详细描述。通常,不应该描述“怎么做”,除非是一些复杂的算法。文档字符串应该提供足够的信息,当别人编写代码调用该函数时,他不需要看一行代码,只要看文档字符串就可以了。

文档字符串有多种风格,比如 Google 风格和 Numpy 风格,这里比较推荐 Numpy 风格的文档字符串,基本写法如下述代码所示:

复制def download_song(song_info: SongInfo, save_dir: str, quality=SongQuality.STANDARD) -> str:
    """ download online music to local

    Parameters
    ----------
    song_info: SongInfo
        song information

    save_dir: str
        directory to save the downloaded audio file

    quality: SongQuality
        song sound quality

    Returns
    -------
    song_path: str
        save path of audio file, empty string when the download fails

    Raises
    ------
    AudioQualityError:
        thrown when the sound quality is illegal
    """
    pass

块注释和行注释

最需要写注释的是代码中那些技巧性的部分,对于复杂的操作,应该在其操作开始前写上若干行注释。对于不是一目了然的代码, 应在其行尾添加注释。为了提高可读性, 注释应该至少离开代码 2 个空格。

复制# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
if i & (i-1) == 0:        # True if i is 0 or a power of 2.

另一方面,绝不要描述代码,阅读代码的人可能比你更懂 Python,他只是不知道你的代码要做什么.

复制# BAD COMMENT: increase i
i += 1

缩进

用 4 个空格来缩进代码,绝对不要用 tab, 也不要 tab 和空格混用。对于行连接的情况,应该垂直对齐换行的元素, 或者使用 4 空格的悬挂式缩进(这时第一行不应该有参数)。

哎呦不错哦:

复制# 垂直对齐参数
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# 字典内垂直对齐
foo = {
    "long_dictionary_key": value1 +
                           value2,
    ...
}

# 4 个空格的悬挂缩进,左括号后面没有参数
foo = long_function_name(
    var_one,
    var_two,
    var_three,
    var_four
)

# 字典内 4 个空格的悬挂缩进
foo = {
    "long_dictionary_key":
        long_dictionary_value,
    ...
}

那种事情不要啊:

复制# 左括号后不能携带参数
foo = long_function_name(var_one, var_two,
    var_three, var_four
)


# 禁止 2 个空格的悬挂式缩进
foo = long_function_name(
  var_one,
  var_two,
  var_three,
  var_four
)

# 字典内需要使用悬挂缩进
foo = {
    "long_dictionary_key":
    long_dictionary_value,
    ...
}

编写代码时不能缩进过多的层级,一般不要超过 4 层,不然会造成阅读困难。Python 中的缩进一般来自于 if-elsefor 和 while 等语句块,一种减少缩进的方法是写 if 就不写 else,比如:

复制def update_by_ids(self, entities: List[Entity]) -> bool:
    """ update multi records

    Parameters
    ----------
    entities: List[Entity]
        entity instances

    Returns
    -------
    success: bool
        whether the update is successful
    """
    # 不满足条件直接返回默认值
    if not entities:
        return True

    # 假设这是一堆很复杂的业务代码
    db = self.get_database()
    db.transaction()

    # 创建 sql 语句
    id_ = self.fields[0]
    values = ','.join([f'{i} = :{i}' for i in self.fields[1:]])
    sql = f"UPDATE {self.table} SET {values} WHERE {id_} = :{id_}"
    self.query.prepare(sql)

    return db.commit()

标签:函数,计算,单行函数,功能,代码
来源: