• 使用JSDoc让你的代码变得能说会道
  • 发布于 1个月前
  • 67 热度
    0 评论
前言
在编程的世界里,我们总希望代码能够自我表达,但现实往往却是“代码千万行,注释没几行”。当你接手一段没有注释的代码时,是不是感觉自己像个占卜师,试图解读前任开发者的心思?别急,今天咱们就来聊聊如何用JSDoc这本“魔法书”来施法,让你的代码变得能说会道!

JSDoc:代码的“翻译官”
JSDoc不仅仅是注释,它是代码的“翻译官”,能让代码的意图跃然纸上。它通过特定的注释格式,为编辑器和IDE提供了丰富的上下文信息,从而实现智能提示、类型检查等功能。接下来,就让我们一起来看看JSDoc的魔力吧!

@param:参数的自我介绍
/**
 * 计算两个数字的和
 * @param {number} a 第一个加数
 * @param {number} b 第二个加数
 * @returns {number} 两数之和
 */
function sum(a, b) {
  return a + b;
}
有了@param,每个参数都仿佛会说话,告诉后来者它们的名字和身份。

@returns:函数的承诺
/**
 * 描述一个数字是否为偶数
 * @param {number} num 要检查的数字
 * @returns {boolean} 如果数字是偶数,返回true,否则返回false
 */
function isEven(num) {
  return num % 2 === 0;
}
@returns是函数的承诺,它告诉你函数会返回什么样的结果。

@typedef:自定义类型的诞生
/**
 * @typedef {Object} Point
 * @property {number} x - 水平坐标
 * @property {number} y - 垂直坐标
 */

/**
 * 计算两点之间的距离
 * @param {Point} point1 第一个点
 * @param {Point} point2 第二个点
 * @returns {number} 两点之间的距离
 */
function calculateDistance(point1, point2) {
  const dx = point1.x - point2.x;
  const dy = point1.y - point2.y;
  return Math.sqrt(dx * dx + dy * dy);
}
通过@typedef,我们可以定义自己的类型,让代码更加清晰和易于管理。

@example:用实例说话
/**
 * 一个简单的加法函数
 * @param {number} a 第一个加数
 * @param {number} b 第二个加数
 * @returns {number} 两数之和
 * @example
 * console.log(add(1, 2)); // 输出:3
 */
function add(a, b) {
  return a + b;
}
@example让函数通过实例来展示它的用法,比长篇大论的说明更加直观。

@deprecated:告别旧时光
/**
 * 一个已经被废弃的方法
 * @deprecated 从版本2.0起,推荐使用`newFunction`替代
 */
function oldFunction() {
  console.warn('这个方法已经被废弃了');
}
@deprecated是向过去告别的标签,它告诉开发者,是时候向前看了。

总结:JSDoc——代码的“语言大师”
通过这篇文章,我们一起学习使用JSDoc来提升代码的表达能力。它不仅提高了代码的可读性和可维护性,还能在不引入TypeScript的情况下,享受到类型标注的便利。

在实际开发中,我的经验是,不要等到代码写完后再去写注释,而是在编写代码的同时,用JSDoc来记录你的思考和决策。这样,无论是现在还是未来,无论是你自己还是其他开发者,都能快速理解代码的意图。记住,代码是给人看的,JSDoc只是一个辅助工具,它不能代替清晰的代码逻辑和良好的编程习惯。
用户评论