前言

Python编程规范通常遵循PEP（Python Enhancement Proposal）系列文档，其中PEP 8是最广为人知的编码风格指南。

以下是一些Python编程规范的基本点：

代码布局

使用4个空格的缩进，而非Tab。
每行不应超过79个字符（或可配置为100，但不建议超过这个长度）。
在二元运算符两边以及逗号后面使用一个空格。但是括号内部不需要空格。
在函数调用的左括号前不应有空格。
在注释中，总是尽量保持至少两个空格的缩进。
当需要换行时，尽量在括号（小括号、中括号、大括号）前换行。

命名规范

文件名

使用snake_case作为文件名的命名约定。
例如：my_script.py、data_processor.py。

代码

类名应该使用驼峰命名法（CapWords）。
使用snake_case作为变量名和函数名的命名约定。
常量应该使用全大写字母和下划线。
避免使用Python保留字作为变量名、函数名等。

异常

异常类命名应该使用Error作为后缀。
尽量不要忽略异常，除非有明确的理由。

代码格式

导入

通常在文件的顶部放置导入。
使用绝对导入。从一个包内部导入时，总是使用包的绝对路径。
避免不必要的导入。

空行

顶级函数和类定义之间应该有两个空行。
类内的方法定义之间应该有一个空行。

注释

注释是提高代码可读性和可维护性的重要工具。以下是一些关于注释的规范及示例，这些规范旨在帮助你编写清晰、有效的注释。

模块级注释：

文件顶部的模块注释应该简明扼要地描述该文件的功能和目的。

示例：

"""
模块名称: data_cleaning
描述: 该模块用于数据清理和预处理。包括去除缺失值、标准化数据等操作。
"""

函数和方法注释：

函数和方法应有文档字符串（docstring），描述函数的目的、参数、返回值和可能引发的异常。

示例：

def clean_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """
    清理数据，包括去除缺失值和重复项。
    
    参数:
        data (List[Dict[str, Any]]): 待处理的数据列表，每个元素是一个字典。

    返回:
        List[Dict[str, Any]]: 清理后的数据列表。

    异常:
        ValueError: 如果数据格式不正确。
    """
    # 函数实现

类注释：

类的文档字符串应描述类的功能、用途以及主要方法的概述。

示例：

class DataCleaner:
    """
    数据清理类，用于处理和清理原始数据。
    
    方法:
        clean_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
            清理数据，包括去除缺失值和重复项。
    """
    
    def __init__(self, threshold: int):
        """
        初始化 DataCleaner 实例。
        
        参数:
            threshold (int): 数据清理的阈值。
        """
        self.threshold = threshold

行内注释：

对于较复杂的代码行或逻辑，使用行内注释来解释代码的功能。

行内注释应简短且紧跟在代码行的旁边。

示例：

1	result = data * factor # 计算结果，factor是用于缩放的因子

块注释：

对于较复杂的代码块或逻辑，使用块注释来分隔和解释代码段。块注释应与代码块对齐，并用#符号开头。

示例：

# 计算每个数据点的标准化值
# 标准化公式: (x - mean) / std
for i in range(len(data)):
    data[i] = (data[i] - mean) / std

代码质量

全局变量

避免全局变量的使用，因为它们可能导致代码难以维护和测试。在必要时，使用global关键字明确声明全局变量。

类型注解

Python 3.5引入了类型注解（也称为类型提示）。

虽然Python是一种动态类型语言，但类型注解可以帮助提高代码的可读性和可维护性，同时也便于使用类型检查工具（如mypy）进行静态类型检查。建议在新项目中使用类型注解。

类型注解说明

Python类型注解（Type Hints）是一种用于指定变量、函数参数和返回值类型的语法，它可以提高代码的可读性和可维护性，并帮助开发工具和静态分析工具（如mypy）进行类型检查。

Python的类型注解在PEP 484中进行了定义，并在Python 3.5及以后版本中得到支持。

以下是一些关于Python类型注解的基本概念和示例：

基本类型

变量注解：

变量类型注解用于指定变量的数据类型。

示例：
1
2
age: int = 30
name: str = "Alice"

函数参数和返回值注解：

使用->语法指定函数的返回值类型，参数类型直接在参数名称后面指定。

示例：
1
2
def greet(name: str) -> str:
return f"Hello, {name}!"

常用类型

基本类型：

int、float、bool、str 等。

示例：

1 2	def add(x: int, y: int) -> int: return x + y

集合类型：

使用List、Tuple、Dict、Set等类型注解集合类型数据。

示例：

from typing import List, Tuple, Dict, Set

def process_numbers(numbers: List[int]) -> Set[int]:
    return set(numbers)

def get_person() -> Tuple[str, int]:
    return "Alice", 30

def get_user_info() -> Dict[str, str]:
    return {"name": "Alice", "email": "alice@example.com"}

更复杂的类型

联合类型（Union）：

使用Union指定一个值可以是多种类型中的一种。

示例：

from typing import Union

def stringify(value: Union[int, float]) -> str:
    return str(value)

可选类型（Optional）：

Optional 是 Union 和 None 的简写，表示一个值可以是某种类型或 None。

示例：

from typing import Optional

def find_item(item_id: int) -> Optional[str]:
    # 如果找不到项，返回 None
    return "item_name" if item_id == 1 else None

类型别名（Type Alias）：

为复杂的类型创建别名，以简化代码。

示例：

from typing import Dict

UserInfo = Dict[str, str]

def get_user_info() -> UserInfo:
    return {"name": "Alice", "email": "alice@example.com"}

泛型（Generic）：

在定义类或函数时使用泛型来处理多种类型。

示例：

from typing import TypeVar, Generic, List

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self):
        self.items: List[T] = []

    def push(self, item: T) -> None:
        self.items.append(item)

    def pop(self) -> T:
        return self.items.pop()

dataclasses模块

Python 3.7引入了dataclasses模块，它可以用来自动生成类的常见方法（如__init__、__repr__、__eq__等），同时支持类型注解。

示例：

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int

def get_person() -> Person:
    return Person(name="Alice", age=30)

使用类型注解的好处

提高可读性：

使代码的意图更清晰，特别是在复杂函数和数据结构中。
帮助静态分析：

工具如mypy可以在代码运行之前检查类型错误。
改善IDE支持：

提供更好的自动补全和错误提示功能。

类型注解是Python的一种可选特性，可以提高代码的质量和维护性，但并不是强制要求的。

在编写代码时，可以根据项目的需求和团队的标准决定是否使用。

我是码客，我是全栈工程师，我为自己代言。

Python编程规范及类型注解的使用说明

前言