命名约定

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-else、for 和 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()

本站声明：
1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；

2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；

3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；

4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；

5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。