整洁代码之道：编写可维护的代码

整洁代码之道：编写可维护的代码

代码被阅读的次数远多于被编写的次数。编写整洁的代码不仅是一种职业素养，更是对团队和未来自己的尊重。本文将分享编写可维护代码的核心原则和实用技巧。

一、有意义的命名

// 不好的命名
var d;  // 过于简短
var data;  // 太泛
var flag;  // 含义不明
var userList1;  // 数字后缀
var temp;  // 临时变量

// 好的命名
var elapsedTimeInDays;
var activeUsers;
var isVip;
var userProfile;
var unverifiedAccounts;

// 函数命名 - 动词开头
function getUserById(id) { }      // 获取
function calculateTotal(items) { } // 计算
function validateEmail(email) { }  // 验证
function isAdult(age) { }         // 判断
function createOrder(data) { }    // 创建

// 类命名 - 名词
class UserRepository { }
class PaymentGateway { }
class EmailValidator { }

二、函数设计

// 原则1：短小精悍 - 每个函数只做一件事
// 不好：一个函数做多件事
function processOrder(order) {
    validateOrder(order);
    var total = calculateTotal(order);
    saveToDatabase(order, total);
    sendEmail(order);
    updateInventory(order);
}

// 好：拆分为多个小函数，主函数只做编排
function processOrder(order) {
    validateOrder(order);
    var total = calculateTotal(order);
    persistOrder(order, total);
    notifyCustomer(order);
}

// 原则2：参数越少越好
// 不好
function createUser(name, email, age, role, department) { }

// 好：使用对象参数
function createUser(userInfo) { }
createUser({
    name: "张三",
    email: "test@example.com",
    age: 25,
    role: "developer",
    department: "engineering"
});

// 原则3：没有副作用
// 不好：修改了外部状态
var globalDiscount = 0;
function applyDiscount(order) {
    globalDiscount = order.amount * 0.1;  // 副作用！
    return order.amount - globalDiscount;
}

// 好：纯函数
function calculateDiscount(amount, rate) {
    return amount * rate;
}

三、注释的艺术

// 不好的注释 - 描述做了什么
// 增加计数
counter++;

// 检查是否为空
if (name === "") { }

// 好的注释 - 解释为什么这样做
// 使用3次重试是因为第三方API偶尔超时
var MAX_RETRIES = 3;

// 时区偏移8小时（北京时间UTC+8）
var offset = 8 * 60 * 60 * 1000;

// 最好：让代码自己说话，减少注释需求
// 不好
if (user.age >= 18) {  // 检查是否成年 }

// 好
if (isAdult(user)) { }

function isAdult(user) {
    return user.age >= 18;
}

四、错误处理

// 使用异常而非错误码
// 不好
function deletePage(page) {
    if (deletePageFromDisk(page) === ERROR) {
        return ERROR;
    }
    if (deleteReferences(page) === ERROR) {
        return ERROR;
    }
    return SUCCESS;
}

// 好
function deletePage(page) {
    try {
        deletePageFromDisk(page);
        deleteReferences(page);
    } catch (error) {
        logError(error);
        throw error;
    }
}

// 提供有意义的错误信息
// 不好
throw new Error("Invalid input");

// 好
throw new Error("用户邮箱格式不正确: " + email);

整洁代码不是一蹴而就的，而是持续打磨的结果。每一次提交都应该让代码比之前更好一点。养成写完代码后回头审视的习惯，问自己：这段代码半年后我还能看懂吗？如果答案是犹豫的，那就重构它。