1. 为什么需要代码风格指南？

本文中大部分内容来自ChatGPT。

代码风格指南是一种旨在促进代码可读性、可维护性和可重用性的约定。虽然它们并不强制执行特定的编码标准，但它们建议一些最佳实践和常规约定，以帮助开发者编写更具一致性、可读性和可维护性的代码。

以下是一些代码风格指南的重要原因：

可读性：代码风格指南可以帮助开发者编写更加可读的代码。这有助于降低代码维护成本，因为代码更容易理解和修改。
一致性：代码风格指南可以确保代码在整个项目中保持一致的外观和感觉。这有助于提高代码可维护性和可重用性，因为开发者可以更轻松地了解代码如何工作。
错误：代码风格指南可以减少编码错误的可能性。例如，强制实施缩进约定可以防止不正确的缩进导致的语法错误。
沟通：代码风格指南可以提高代码的可交流性，因为开发者可以轻松地了解代码中使用的惯用语和惯例。
最佳实践：代码风格指南可以提供最佳实践和规则，以确保开发人员遵循最佳实践和规则，以提高代码质量和可重用性。

在现代软件开发中，代码风格指南已成为一种非常重要的约定，以帮助团队开发一致、可读性强且易于维护的代码。

本文中，我们来学习一下Google Python代码风格指南。

参考文档：

2. 关键十条

缩进使用四个空格。不要使用制表符，也不要混合使用空格和制表符。
变量和函数名应该是小写字母，用下划线分隔单词。模块名应该是小写字母，用下划线分隔单词。
类名应该是驼峰式命名，即首字母大写，后续单词首字母也大写。
模块级别的常量应该使用全大写字母和下划线分隔单词。
函数和方法参数应该使用self、cls作为实例方法和类方法的第一个参数。
行的长度不应该超过80个字符，注释的行长度不应该超过72个字符。
使用文档字符串（Docstrings）对模块、函数、类和方法进行文档化。
在类定义中使用无参的super()调用父类构造函数。
使用list comprehension来替代for循环进行列表操作。
每个模块应该具有如下的结构：文件注释、模块导入、常量定义、函数定义、类定义等。

除了这十条规则之外，还有很多其他的编码规范需要开发者遵循，以确保代码的质量和可维护性。

3. Docstring

代码风格指南中的内容非常多，如果说哪个最重要，我认为是Docstring（文档字符串）。

Docstring指南：

模块级别的文档应该在模块的顶部使用文档字符串进行描述。
函数、类和方法应该在其定义之后的第一行使用文档字符串进行描述。
使用三重引号来创建文档字符串，并确保文档字符串格式正确。
文档字符串的第一行应该是一个简要的摘要，概括函数、类或方法的功能。
在文档字符串的第一行之后，应该使用一个空白行分隔摘要和详细描述。
在文档字符串的详细描述中，可以提供更多有关函数、类或方法的信息，包括参数、返回值、异常、实现细节等。
参数和返回值应该按照参数名称和类型进行描述，并在它们之前添加“Args”和“Returns”等关键词。
异常应该按照异常类型进行描述，并在它们之前添加“Raises”关键词。
在类的文档字符串中，应该描述类的构造函数和所有公共方法。
在函数和方法的文档字符串中，应该描述函数或方法的参数、返回值、异常、实现细节等。

函数和方法的Docstring示例：

def fetch_smalltable_rows(
    table_handle: smalltable.Table,
    keys: Sequence[bytes | str],
    require_all_keys: bool = False,
) -> Mapping[bytes, tuple[str, ...]]:
    """Fetches rows from a Smalltable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.

    Args:
        table_handle: An open smalltable.Table instance.
        keys: A sequence of strings representing the key of each table
          row to fetch.  String keys will be UTF-8 encoded.
        require_all_keys: If True only rows with values set for all keys will be
          returned.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {b'Serak': ('Rigel VII', 'Preparer'),
         b'Zim': ('Irk', 'Invader'),
         b'Lrrr': ('Omicron Persei 8', 'Emperor')}

        Returned keys are always bytes.  If a key from the keys argument is
        missing from the dictionary, then that row was not found in the
        table (and require_all_keys must have been False).

    Raises:
        IOError: An error occurred accessing the smalltable.
    """

类的Docstring示例：

class SampleClass:
    """Summary of class here.

    Longer class information...
    Longer class information...

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam: bool = False):
        """Initializes the instance based on spam preference.

        Args:
          likes_spam: Defines if instance exhibits this preference.
        """
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

块和行的Docstring示例：

# 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.

VSCode中的自动生成Docstring的方法，参考文档《VSCode常用快捷键和配置》

4. 后记

更多详细内容，请移步阅读Google Python Style Guide

一个计算机技术爱好者与学习者

好好学Python：Python代码风格指南

1. 为什么需要代码风格指南？

2. 关键十条

3. Docstring

4. 后记