代码风格指南

代码风格是团队协作开发的基础，统一的代码风格能够提高代码的可读性、可维护性，并减少团队成员间的沟通成本。

命名规范

变量和函数命名

使用有意义的名称

Good:

javascript

// 清晰表达意图的变量名
const maxRetryAttempts = 3;
const isLoggedIn = checkUserAuthStatus();
const userAccountBalance = calculateBalance(userId);

// 清晰表达意图的函数名
function calculateTotalPrice(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function validateUserEmail(email) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

Bad:

javascript

// 意图不明确的变量名
const x = 3;
const flag = checkUserAuthStatus();
const bal = calculateBalance(userId);

// 意图不明确的函数名
function calc(items) {
  return items.reduce((a, b) => a + b.price, 0);
}

function check(email) {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
}

常量命名

Good:

javascript

// 使用大写字母和下划线
const MAX_RETRY_ATTEMPTS = 3;
const API_BASE_URL = 'https://api.example.com';
const DEFAULT_TIMEOUT_MS = 5000;

Bad:

javascript

// 不规范的常量命名
const max_retry_attempts = 3;
const apiBaseUrl = 'https://api.example.com';
const defaultTimeout = 5000;

类和构造函数命名

Good:

javascript

// 使用PascalCase
class UserAccount {
  constructor(userData) {
    this.data = userData;
  }
}

class PaymentProcessor {
  process(paymentData) {
    // 处理支付逻辑
  }
}

Bad:

javascript

// 不规范的类命名
class userAccount {
  // ...
}

class payment_processor {
  // ...
}

代码格式化

缩进和空格

Good:

javascript

// 一致的缩进（通常使用2或4个空格）
function processData(data) {
  if (data && data.items) {
    return data.items.map(item => {
      return {
        id: item.id,
        name: item.name,
        processed: true
      };
    });
  }
  return [];
}

Bad:

javascript

// 不一致的缩进
function processData(data){
if(data && data.items){
    return data.items.map(item=>{
      return{
          id:item.id,
      name:item.name,
           processed:true
      };
    });
}
  return[];
}

空行使用

Good:

javascript

// 适当的空行分隔逻辑块
class UserService {
  constructor(apiClient) {
    this.apiClient = apiClient;
    this.cache = new Map();
  }

  async getUser(userId) {
    if (this.cache.has(userId)) {
      return this.cache.get(userId);
    }

    const userData = await this.apiClient.fetchUser(userId);
    this.cache.set(userId, userData);
    
    return userData;
  }

  clearCache() {
    this.cache.clear();
  }
}

Bad:

javascript

// 缺乏适当的空行分隔
class UserService {
  constructor(apiClient) {
    this.apiClient = apiClient;
    this.cache = new Map();
  }
  async getUser(userId) {
    if (this.cache.has(userId)) {
      return this.cache.get(userId);
    }
    const userData = await this.apiClient.fetchUser(userId);
    this.cache.set(userId, userData);
    return userData;
  }
  clearCache() {
    this.cache.clear();
  }
}

注释规范

函数注释

Good:

javascript

/**
 * 计算购物车总价
 * @param {Array} items - 购物车商品数组
 * @param {Object} options - 计算选项
 * @param {boolean} options.includeTax - 是否包含税费
 * @param {number} options.discount - 折扣百分比
 * @returns {number} 计算后的总价
 */
function calculateCartTotal(items, options = {}) {
  const { includeTax = false, discount = 0 } = options;
  
  let subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  
  if (includeTax) {
    subtotal *= 1.1; // 假设税率10%
  }
  
  return subtotal * (1 - discount / 100);
}

Bad:

javascript

// 缺乏详细注释或注释不准确
function calc(items, opts) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += items[i].price * items[i].qty;
  }
  // 计算总价
  return total * 1.1;
}

代码内注释

Good:

javascript

function processPayment(paymentData) {
  // 验证支付数据的完整性
  if (!validatePaymentData(paymentData)) {
    throw new Error('Invalid payment data');
  }

  // 检查账户余额是否充足
  const accountBalance = getAccountBalance(paymentData.userId);
  if (accountBalance < paymentData.amount) {
    throw new Error('Insufficient balance');
  }

  // 执行支付处理
  return executePayment(paymentData);
}

Bad:

javascript

function processPayment(paymentData) {
  if (!validatePaymentData(paymentData)) {
    throw new Error('Invalid payment data');
  }
  // TODO: check balance
  const accountBalance = getAccountBalance(paymentData.userId);
  // might need to add more validation here
  return executePayment(paymentData);
}

函数设计

函数长度

Good:

javascript

// 简洁、专注的函数
function formatUserName(user) {
  return `${user.firstName} ${user.lastName}`;
}

function validateUser(user) {
  return user && user.email && isValidEmail(user.email);
}

function getUserDisplayName(user) {
  if (!validateUser(user)) {
    return 'Unknown User';
  }
  
  return formatUserName(user);
}

Bad:

javascript

// 过长、职责不清的函数
function processUserData(userData) {
  // 格式化用户名
  let formattedName = '';
  if (userData && userData.firstName && userData.lastName) {
    formattedName = userData.firstName + ' ' + userData.lastName;
  } else if (userData && userData.username) {
    formattedName = userData.username;
  } else {
    formattedName = 'Unknown User';
  }
  
  // 验证邮箱
  let emailValid = false;
  if (userData && userData.email) {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    emailValid = emailRegex.test(userData.email);
  }
  
  // 处理其他数据...
  // 更多逻辑...
  
  return { name: formattedName, emailValid };
}

参数设计

Good:

javascript

// 使用对象参数提高可读性
function createUser({ 
  name, 
  email, 
  role = 'user', 
  isActive = true 
}) {
  return {
    id: generateId(),
    name,
    email,
    role,
    isActive,
    createdAt: new Date()
  };
}

// 使用示例
const newUser = createUser({
  name: 'John Doe',
  email: 'john@example.com',
  role: 'admin'
});

Bad:

javascript

// 难以理解的参数列表
function createUser(name, email, role, isActive, createdAt, permissions) {
  return {
    id: generateId(),
    name: name,
    email: email,
    role: role || 'user',
    isActive: isActive !== undefined ? isActive : true,
    createdAt: createdAt || new Date(),
    permissions: permissions || []
  };
}

// 使用示例 - 难以理解每个参数的含义
const newUser = createUser('John Doe', 'john@example.com', 'admin', true, new Date(), []);

错误处理

一致的错误处理

Good:

javascript

class ApiService {
  async fetchData(url, options = {}) {
    try {
      const response = await fetch(url, {
        method: options.method || 'GET',
        headers: {
          'Content-Type': 'application/json',
          ...options.headers
        },
        ...options
      });

      if (!response.ok) {
        throw new Error(`HTTP Error: ${response.status} - ${response.statusText}`);
      }

      return await response.json();
    } catch (error) {
      // 记录错误并重新抛出
      console.error('API request failed:', error);
      throw error;
    }
  }
}

Bad:

javascript

class ApiService {
  async fetchData(url, options = {}) {
    // 缺乏错误处理
    const response = await fetch(url, options);
    return await response.json();
  }
}

代码组织

模块结构

Good:

javascript

// user-service.js
// 1. 导入依赖
import { validateEmail } from './validators.js';
import { generateId } from './utils.js';

// 2. 私有辅助函数
function hashPassword(password) {
  // 密码哈希逻辑
}

// 3. 主要导出函数
export async function createUser(userData) {
  if (!validateEmail(userData.email)) {
    throw new Error('Invalid email address');
  }
  
  return {
    id: generateId(),
    email: userData.email,
    passwordHash: hashPassword(userData.password),
    createdAt: new Date()
  };
}

// 4. 其他导出
export { validateEmail };

Bad:

javascript

// 无序的代码组织
export { validateEmail };

function hashPassword(password) { /* ... */ }

import { validateEmail } from './validators.js'; // 在函数后导入

export async function createUser(userData) {
  // 逻辑混合
}

function generateId() { /* ... */ } // 辅助函数在主要函数后定义

遵循这些代码风格指南，可以显著提高代码的可读性和可维护性，促进团队协作效率。

代码风格指南 #

命名规范 #

变量和函数命名 #

使用有意义的名称 #

常量命名 #

类和构造函数命名 #

代码格式化 #

缩进和空格 #

空行使用 #

注释规范 #

函数注释 #

代码内注释 #

函数设计 #

函数长度 #

参数设计 #

错误处理 #

一致的错误处理 #

代码组织 #

模块结构 #

代码风格指南

命名规范

变量和函数命名

使用有意义的名称

常量命名

类和构造函数命名

代码格式化

缩进和空格

空行使用

注释规范

函数注释

代码内注释

函数设计

函数长度

参数设计

错误处理

一致的错误处理

代码组织

模块结构