白骑士的Python教学附加篇 5.2 代码规范与最佳实践

原创已于 2024-07-01 16:16:20 修改 · 950 阅读

19 ·

CC 4.0 BY-SA版权

文章标签：

#代码规范 #python #开发语言

于 2024-07-01 16:14:02 首次发布

教学同时被 3 个专栏收录

339 篇文章

订阅专栏

Python

41 篇文章

订阅专栏

代码规范

4 篇文章

订阅专栏

系列目录

上一篇：白骑士的Python教学附加篇 5.1 Python开发工具

PEP 8标准

PEP 8，即Python Enhancement Proposal 8，是Python的官方编码风格指南。它由Guido van Rossum等人在2001年编写，旨在提高代码的可读性，使Python代码在各个项目中具有一致的风格。以下是PEP 8中的一些关键要点：

缩进

使用4个空格进行缩进；
不要使用制表符进行缩进。

例如：

def my_function():
    if True:
        print("Hello, World!")

最大行宽

每行代码的长度应不超过79个字符；
文档字符串或注释的长度应不超过72个字符。

空行

顶层定义之间使用两个空行；
类和函数定义内的定义之间使用一个空行。

例如：

class MyClass:
    def __init__(self):
        self.value = 0

    def method(self):
        pass

导入

导入应该在文件的顶部，紧跟在模块的文档字符串和注释之后；
导入应该分为三个部分：标准库导入、第三方库导入、本地应用/库的导入，每部分之间用空行分隔。

例如：

import os
import sys

import requests

from my_module import my_function

空格

在二元运算符两侧各保留一个空格，例如赋值（=）、比较（==、>、<等）、算术运算（+、-、*、/等）；
函数参数列表、索引或切片的括号内不要添加空格。

例如：

x = 5
y = x + 2
z = (x + y) * 2

注释

使用完整的句子编写注释；
行注释应独占一行，并且与代码对齐；
块注释应与其后代码缩进级别一致，且每行以#和一个空格开始。

例如：

# 这是一个行注释

def complex_function(x, y):
    # 这是一个块注释
    # 详细解释该块代码的功能
    result = x + y

    return result

文档字符串

所有公共模块、函数、类和方法都应使用文档字符串进行说明。
文档字符串应包含对参数、返回值、异常等的说明。

例如：

def my_function(param1, param2):

    """
    计算并返回两个参数的和。
    Args:
        param1 (int): 第一个参数。
        param2 (int): 第二个参数。

    Returns:
        int: 参数的和。
    """

    return param1 + param2

命名约定

模块名应使用小写字母，可以使用下划线分隔；
类名应使用大写字母开头的驼峰式命名法；
函数名和变量名应使用小写字母，可以使用下划线分隔；
常量名应使用全部大写字母，并使用下划线分隔。

例如：

# 模块名
import my_module


# 类名
class MyClass:
    pass


# 函数名和变量名
def my_function():
    my_variable = 10
    return my_variable


# 常量名
MY_CONSTANT = 100

常见编码规范

除了PEP 8标准外，还有一些通用的编码规范和最佳实践，可以帮助你编写更加清晰、可维护的代码。

遵循单一职责原则

每个函数或类应只负责一项任务，这样可以提高代码的可读性和可维护性，例如：

def read_file(file_path):
    with open(file_path, 'r') as file:
        return file.read()


def process_data(data):
    return data.splitlines()


def write_file(file_path, data):
    with open(file_path, 'w') as file:
        file.write('\n'.join(data))

避免魔术数

魔术数是指代码中未解释的数字，应该使用具有描述性的常量代替，例如：

# 避免魔术数
DISCOUNT_RATE = 0.1


def apply_discount(price):
    return price * (1 - DISCOUNT_RATE)

使用上下文管理器

对于需要在完成后自动清理的资源（如文件、网络连接等），应使用上下文管理器，例如：

# 使用上下文管理器处理文件
with open('file.txt', 'r') as file:
    data = file.read()

尽量使用内置函数和库

Python的标准库和内置函数经过高度优化，使用它们可以提高代码的效率和可读性，例如：

# 使用内置函数代替手动实现
numbers = [1, 2, 3, 4, 5]
total = sum(numbers)

注重代码的可测试性

编写易于测试的代码，使单元测试覆盖每个功能模块，确保代码的正确性和可靠性，例如：

# 示例单元测试
import unittest


def add(a, b):
    return a + b


class TestAddFunction(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(1, 2), 3)
        self.assertEqual(add(-1, 1), 0)


if __name__ == '__main__':
    unittest.main()

保持函数短小

一个函数应尽量保持短小，完成单一功能。过长的函数会降低代码的可读性和可维护性，例如：

# 将长函数拆分为多个小函数
def analyze_data(data):
    clean_data = clean(data)
    results = compute_statistics(clean_data)
    visualize(results)


def clean(data):
    # 数据清洗逻辑
    pass


def compute_statistics(clean_data):
    # 计算统计量逻辑
    pass


def visualize(results):
    # 数据可视化逻辑
    pass

使用日志记录

在开发和调试过程中，使用日志记录比使用打印语句更加灵活和专业。Python的 ‘logging’ 模块提供了丰富的日志功能，例如：

import logging


# 配置日志
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')


def process_data(data):
    logging.info('Processing data...')
    # 数据处理逻辑
    logging.info('Data processed successfully')


# 调用函数
process_data('sample data')

保持代码的一致性

团队合作时，确保整个团队遵循相同的编码规范和风格指南，这有助于提高代码的可读性和可维护性。

定期重构代码

随着项目的发展，代码可能会变得复杂且难以维护。定期重构代码可以提高代码质量，使其更加简洁、清晰和高效，例如：

# 重构前的代码
def process(data):
    result = []

    for item in data:
        if item % 2 == 0:
            result.append(item * 2)

    return result


# 重构后的代码
def process(data):
    return [item * 2 for item in data if item % 2 == 0]

编写文档

为代码编写详细的文档，包括模块、类、函数的说明，以及使用示例和注意事项，帮助其他开发者理解和使用代码，例如：

def calculate_area(radius):

    """
    计算圆的面积。
    Args:
        radius (float): 圆的半径。

    Returns:
        float: 圆的面积。

    Raises:
        ValueError: 如果半径为负值。
    """

    if radius < 0:
        raise ValueError('半径不能为负值')

    return 3.14159 * radius ** 2