JavaScript 函数与方法详解：规范命名、参数处理与纯函数设计

函数与方法的核心区别

在 JavaScript 中，理解函数（Function）和方法（Method）的差异是编写面向对象风格代码的基础：

• 函数（function）：一段带有名称和参数的独立代码块，可以被多次调用。它通常作为全局作用域或模块级别的实体存在。
• 方法（method）：当一个函数被赋值给对象的属性时，它就成为了“方法”。方法与特定的对象实例相关联，可以通过 object.method() 的形式进行调用。

简而言之，方法是依附于对象的特殊函数。其数据传递方式也有所不同：函数通过显式参数传递数据，而方法往往通过 this 隐式获取对象内部状态。

如何编写高质量的函数

第1步：确保命名语义清晰准确

良好的命名是代码可读性的第一要素。避免为了缩短代码行数而牺牲清晰度。

• 函数命名：建议以动词开头，如 getXxxx、setXxxx 或 calculateAmount，直观表达功能意图。
• 参数命名：应准确反映入参含义。通用回调可使用 callback 或 fn，但具体业务逻辑必须使用具名参数，降低调用者的认知负荷。

第2步：完善 JSDoc 注释规范

对于工具函数，标准的 JSDoc 注释能显著提升协作效率。注释应包含描述、参数类型、默认值及返回值说明。

/**
 * 时间格式化工具函数
 * @param { (Date | number | string) } date - 目标时间
 * @param { string } [unit = 'second'] - 转换格式，可选参数，默认为秒级精度
 * @returns { string } 格式化后的时间字符串
 */
export const timeFormat = (date: Date | number | string, unit = 'second') => {
  if (!date) return '';
  if (typeof date === 'string') return date;
  if (typeof date === 'number') {
    date = new Date(date);
  }
  const year = date.getFullYear();
  const month = date.getMonth() + 1;
  const day = date.getDate();
  // ... 后续格式化逻辑
};

复杂参数对象的注释写法

当参数为对象时，需逐行解释对象内部的属性定义：

/**
 * @param {Object} employee - 员工信息对象
 * @param {string} employee.name - 员工姓名
 * @param {string} employee.department - 所属部门
 */
Project.prototype.assign = function(employee) {
  // ...
};

第3步：优化参数设计与传递

参数过多会导致调用繁琐且难以维护，建议遵循单一职责原则，并将参数数量控制在合理范围（通常不超过 3 个）。

场景 A：参数较多时的对象解构

当函数需要接收多个参数时，推荐使用配置对象+解构的方式。相比逐个设置默认值，解构允许调用者只传入需要的字段，无需关心顺序，也无需为未修改的参数传递占位符。

// 错误示范：参数多，调用时需填全所有位置
async function print(html, path, dev, or, mode, w, h...) { ... }
print(html, path, '', '', '', 100, 100...); // 冗余

// 推荐做法：使用对象解构
async function printerProxyPrint({
  html_str,
  file_path,
  device = 'pc',
  width = 123,
  height = 123
}) {
  // ...
}
await printerProxyPrint({ html_str, file_path }); // 仅传必要参数

场景 B：防御性编程与类型检查

即使使用了 TypeScript，在处理外部接口返回的数据时，仍应保持防御性思维。不要盲目信任后端数据的结构，应在运行前进行基本的类型守卫：

// 针对可能为 null 或 undefined 的日期对象进行处理
if (!date) {
  return '';
}
// 兼容 string 类型的直接返回
if (typeof date === 'string') return date;
// 将 timestamp 转换为 Date 对象
if (typeof date === 'number') {
  date = new Date(date);
}

第4步：追求幂等与纯函数

为了提高代码的可测试性和可维护性，应尽量编写符合以下特性的函数：

1. 幂等函数（Idempotent）

幂等意味着相同的输入始终产生相同的结果，无状态依赖。

function sum(a, b) {
  return a + b;
}

2. 纯函数（Pure Function）

纯函数除了满足幂等性外，还要求没有副作用，即不修改外部状态或传入的对象引用。

// 非纯函数：直接修改原对象，产生副作用
function addColorNonPure(dog) {
  dog.color = 'white'; 
  return dog;
}

// 纯函数：创建副本后修改，不改变原数据
function addColorPure(dog) {
  const copyDog = Object.assign({}, dog);
  copyDog.color = 'white';
  return copyDog;
}

3. 返回值规范

避免在正常逻辑中返回 null，因为 null 会迫使调用者进行额外的判空处理。return 空数组 []、空对象 {} 或直接抛出异常通常是更优雅的处理方式。

总结

掌握函数命名的规范性、参数设计的灵活性（如解构）、类型检查的安全性以及纯函数设计的思想，是进阶 JavaScript 开发的关键。这些最佳实践不仅能减少运行时错误，还能大幅降低团队协作中的沟通成本与维护难度。

以上就是 JavaScript 基础系列之函数和方法详解的详细内容，更多关于 JavaScript 函数与方法的最佳实践资料请关注本站其它相关文章！