第二课 Python 注释与规范格式

一、注释

1. 什么是注释

我们在上语文的课的时候，当老师讲到不懂的字或者词语，就会增加注释，用来解释字或者词语的意思，以防自己在上完课后忘记。代码注释也是一样的功能，让自己或者其它的代码阅读者可以快速的知道代码的作用。

2. 注释的样式

1）单行注释在Python中多行注释以#开头，后面跟解释的内容，单行注释可以让Python解释器忽略#后的内容（仅限同一行）

Python 复制代码

# 这个函数是Python中的内置函数，函数会将括号中的内容输出到终端
print("Hello Word")

2）多行注释在Python中单行注释以'''开头,同时以'''结尾，''' '''中为解释的内容，多行注释会让Python解释器生成一个字符串，但是由于这个字符串没有绑定任何变量，所以不会产生任何效果

Python 复制代码

'''
1.这个函数是Python中的内置函数
2.函数会将括号里面的内容输出到终端、
'''
print("Hello Word")

3. 注释的使用技巧

使用ctrl+/ 可以快速的对当前行进行注释，再次使用Ctrl+/可以取消注释

二、语句分隔符

句号代表着一句话的结束，在编程语言中语句分隔符相当于标点符号中的句号，用来表示编程语言中编程语句的结束。在Python中用换行或;,推荐使用换行。

三、PEP 8规范与Google Python风格

PEP 8是Python编程语言的官方编码风格指南(Python Enhancement Proposal8)，它提供了一套规范和建议，用于编写清晰、易读和一致的Python代码。PEP 8旨在促进Python代码的可读性，并为Python开发者提供一致的编码样式。类比公文写作格式，规定了每一行的字数、字间距、需要用什么字体等。下面我将列举一些基本的规范：

1. 缩进与行长度

缩进：统一采用四个空格，避免使用Tab键。

Python 复制代码

    def display_message():
        print("Hello from PEP 8 compliant function")

行长限制 ：保持每一行不超过79个字符，长表达式可以使用圆括号自动换行或续行符/。

Python 复制代码

    extended_text = ("When the line becomes too lengthy,"
                    "it's advisable to split into multiple lines.")

2. 命名约定

模块：全小写，单词间以下划线分隔。

Python 复制代码

    example_module.py

类：采用CamelCase命名法。
大驼峰式（UpperCamelCase 或 PascalCase）：每个单词首字母都大写，包括第一个单词。

Python 复制代码

    class SampleClass:
        pass

函数/变量：全部小写，使用下划线分隔词。

Python 复制代码

    def process_data(input_list):
        result = sum(input_list)
        return result

常量：全大写，单词间用下划线分割。

Python 复制代码

    MAX_ATTEMPTS = 5

私有属性：以双下划线开头。

Python 复制代码

    class PrivateData:
        __hidden_value = 'confidential'

3. 表达式与操作符

操作符周围添加一个空格。

Python 复制代码

    result = a + b

4. 空白与空行

函数与类之间保留两行空白。

Python 复制代码

    def greet_user(name):
        print(f"Hello, {name}!")

    class Greeting:
        pass

参数列表内适当增加空格。

Python 复制代码

    def complex_operation(a, b, c):
        return a + b * c

5. 导入语句

标准库 -> 第三方库 -> 自定义模块，每部分之间空行分开。

Python 复制代码

    import os
    import sys

    import numpy as np
    import pandas as pd

    from local_modules import custom_class

6. 注释与文档

单行注释：紧跟代码行，至少两个空格前导。

python 复制代码

    # This is a comment explaining the code below.
    print("Example output")

多行注释：使用三重引号包裹。

Python 复制代码

    """
    A detailed explanation of how this piece of code works.
    Useful for understanding more complicated sections.
    """

文档字符串：每个模块、类及公有方法首行。

Python 复制代码

    """描述其用途的模块级文档字符串。"""

    class ExampleClass:
        """
        类文档在这里。
        描述方法、属性等
        """

        def do_something(self):
            """
            方法执行某些操作。
            self：对象指针。
            """
            pass

Google Python风格基于PEP 8，但在文档字符串、异常处理、导入模块方面做了增强，更适用于大型团队协作。下面是Google Python风格的链接地址：PEP 8中文规范