coding-standards

最近更新: 2025-10-10

跨语言通用编码规范

适用于所有编程语言的通用编码标准和最佳实践

1. 命名规范

1.1 通用原则

• 有意义: 名称应该清楚表达意图
• 可读性: 避免缩写和单字母变量（除了循环计数器）
• 一致性: 在同一项目中保持命名风格一致
• 避免误导: 不使用容易混淆的名称

// ❌ 不好的命名
let d = new Date()
let u = users.filter(x => x.a)
function calc(a, b) { return a * b * 0.1 }

// ✅ 好的命名
let currentDate = new Date()
let activeUsers = users.filter(user => user.isActive)
function calculateDiscount(price, quantity) { return price * quantity * 0.1 }

1.2 函数命名

• 使用动词开头，清楚表达函数的作用
• 布尔函数使用 is、has、can、should 等前缀

# ✅ 好的函数命名
def get_user_by_id(user_id):
def create_new_order(order_data):
def is_valid_email(email):
def has_permission(user, resource):
def can_access_resource(user, resource):

1.3 变量命名

• 使用名词或名词短语
• 集合使用复数形式
• 常量使用全大写（根据语言习惯）

// ✅ 好的变量命名
String userName;
List<User> activeUsers;
final int MAX_RETRY_COUNT = 3;
boolean isProcessing;

2. 函数设计

2.1 单一职责原则

每个函数应该只做一件事，并且把它做好。

// ❌ 职责过多
function processUserData(userData: any) {
  // 验证数据
  if (!userData.email) throw new Error('邮箱必填')
  
  // 保存到数据库
  database.save(userData)
  
  // 发送邮件
  emailService.send(userData.email, 'welcome')
  
  // 记录日志
  logger.info('用户创建成功')
}

// ✅ 职责分离
function validateUserData(userData: UserData): void {
  if (!userData.email) throw new Error('邮箱必填')
}

function saveUser(userData: UserData): User {
  return database.save(userData)
}

function sendWelcomeEmail(email: string): void {
  emailService.send(email, 'welcome')
}

function createUser(userData: UserData): User {
  validateUserData(userData)
  const user = saveUser(userData)
  sendWelcomeEmail(userData.email)
  logger.info('用户创建成功', { userId: user.id })
  return user
}

2.2 参数控制

• 函数参数不超过 3-4 个
• 使用对象传递多个参数
• 提供合理的默认值

# ❌ 参数过多
def create_user(name, email, age, phone, address, city, country, postal_code):
    pass

# ✅ 使用对象封装
def create_user(user_data: UserData):
    pass

# 或使用字典（Python）
def create_user(name: str, email: str, **kwargs):
    age = kwargs.get('age', 18)
    phone = kwargs.get('phone', '')
    # ...