编码规范 (Coding Standards)
编码规范 Coding Standards
良好的编码规范可以提高代码的可读性、可维护性和可扩展性。本指南涵盖了编写高质量代码的最佳实践。
命名规范 Naming Conventions
1. 变量命名
- 使用有意义的描述性名称
- 遵循语言约定（驼峰、下划线等）
- 避免使用单字母变量（除非是循环计数器）
# 好的命名
user_name = "John"
totalAmount = 100.50
isValid = True
# 避免的命名
u = "John" # 太短
a = 100.50 # 不清晰
flag = True # 不具体2. 函数命名
- 使用动词开头
- 清晰表达功能
- 保持一致的命名风格
# 好的命名
def calculate_total_price(items):
pass
def getUserProfile(user_id):
pass
# 避免的命名
def process(data): # 太模糊
def do_stuff(): # 不清晰3. 类命名
- 使用名词
- 采用大驼峰命名法
- 表达类的功能或特征
# 好的命名
class UserManager:
pass
class PaymentProcessor:
pass
# 避免的命名
class Manager: # 太模糊
class Data: # 不具体代码格式 Code Formatting
1. 缩进和空格
# 正确的缩进
def calculate_sum(numbers):
total = 0
for number in numbers:
total += number
return total
# 适当的空格使用
x = a + b * c
list = [1, 2, 3, 4]
dict = {"key": "value"}2. 行长度和换行
# 长行的适当换行
long_string = (
"This is a very long string that needs "
"to be wrapped across multiple lines"
)
def long_function_call(
param1,
param2,
param3
):
pass3. 注释规范
class DataProcessor:
"""
数据处理类
用于处理和转换各种格式的数据。
支持CSV、JSON和XML格式。
"""
def process_data(self, data):
# 检查数据有效性
if not self._is_valid(data):
return None
# 转换数据格式
result = self._transform(data)
return result代码组织 Code Organization
1. 文件结构
#!/usr/bin/env python
"""模块文档字符串"""
# 标准库导入
import os
import sys
# 第三方库导入
import numpy as np
import pandas as pd
# 本地模块导入
from .utils import helper
from .models import user
# 常量定义
MAX_RETRY = 3
DEFAULT_TIMEOUT = 30
# 类定义
class MainClass:
pass
# 主函数
if __name__ == "__main__":
pass2. 类结构
class UserManager:
"""用户管理类"""
def __init__(self):
self._users = {}
# 公共方法
def add_user(self, user):
pass
def get_user(self, user_id):
pass
# 私有方法
def _validate_user(self, user):
pass
def _generate_user_id(self):
pass3. 函数组织
def process_data(data):
"""
处理数据的主函数
Args:
data: 输入数据
Returns:
处理后的数据
Raises:
ValueError: 当数据格式无效时
"""
# 参数验证
if not isinstance(data, dict):
raise ValueError("数据必须是字典格式")
# 主要处理逻辑
result = _transform_data(data)
# 结果验证
if not _is_valid_result(result):
return None
return result错误处理 Error Handling
1. 异常处理
def read_file(filename):
try:
with open(filename, 'r') as f:
return f.read()
except FileNotFoundError:
logger.error(f"文件不存在: {filename}")
raise
except IOError as e:
logger.error(f"读取文件错误: {e}")
return None
finally:
# 清理代码
pass2. 错误检查
def divide(a, b):
# 前置条件检查
if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
raise TypeError("参数必须是数字")
if b == 0:
raise ValueError("除数不能为零")
# 执行操作
result = a / b
# 后置条件检查
assert isinstance(result, float), "结果必须是浮点数"
return result性能优化 Performance Optimization
1. 数据结构选择
# 使用集合进行快速查找
def find_duplicates(items):
seen = set()
duplicates = set()
for item in items:
if item in seen:
duplicates.add(item)
else:
seen.add(item)
return duplicates
# 使用字典进行计数
def count_occurrences(items):
counter = {}
for item in items:
counter[item] = counter.get(item, 0) + 1
return counter2. 算法优化
# 优化循环
def find_sum_pairs(numbers, target):
seen = set()
pairs = []
for num in numbers:
complement = target - num
if complement in seen:
pairs.append((num, complement))
seen.add(num)
return pairs
# 使用生成器
def process_large_file(filename):
def line_generator():
with open(filename) as f:
for line in f:
yield line.strip()
return line_generator()测试实践 Testing Practices
1. 单元测试
import unittest
class TestCalculator(unittest.TestCase):
def setUp(self):
self.calc = Calculator()
def test_add(self):
self.assertEqual(self.calc.add(2, 3), 5)
self.assertEqual(self.calc.add(-1, 1), 0)
def test_divide(self):
self.assertEqual(self.calc.divide(6, 2), 3)
with self.assertRaises(ValueError):
self.calc.divide(1, 0)2. 测试用例设计
def test_user_registration():
# 准备测试数据
user_data = {
"username": "test_user",
"email": "[email protected]",
"password": "password123"
}
# 执行测试
user = register_user(user_data)
# 验证结果
assert user.username == user_data["username"]
assert user.email == user_data["email"]
assert user.is_active == True代码审查 Code Review
1. 审查清单
- 代码是否遵循项目规范
- 是否有适当的错误处理
- 是否有充分的测试覆盖
- 是否有必要的文档
- 是否有性能问题
2. 常见问题
- 重复代码
- 过度复杂的逻辑
- 缺乏错误处理
- 命名不规范
- 注释不充分
最佳实践 Best Practices
-
代码可读性
- 清晰的命名
- 适当的注释
- 简单的逻辑
-
代码可维护性
- 模块化设计
- 单一职责
- 适当的抽象
-
代码可测试性
- 依赖注入
- 接口设计
- 测试驱动开发
-
代码可扩展性
- 开闭原则
- 接口隔离
- 依赖倒置