前端：HTML、CSS、JavaScript 代码注释 / 注释与代码规范

一、HTML 行内注释

HTML注释是在HTML代码中添加说明和解释的一种方法，这些注释不会被浏览器渲染或显示在页面上，而是被浏览器忽略。HTML注释对于代码的可读性、可维护性和团队协作非常重要。

1.1、HTML注释的语法

HTML注释的语法是以结束。在这两个标记之间的任何内容都被视为注释。

1.2、示例

<!DOCTYPE html>  
<html lang="en">  
<head>  
    <meta charset="UTF-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1.0">  
    <title>HTML注释示例</title>  
    <!-- 这是一个HTML注释 -->  
    <!--  
    这是一个多行HTML注释  
    可以跨越多行  
    并包含任何文本  
    -->  
</head>  
<body>  
    <h1>欢迎来到我的网页</h1>  
    <!-- 这里可以放置对h1标签的注释，例如："h1标签用于显示页面主标题" -->  
    <p>这是一个段落。</p>  
</body>  
</html>

1.3、HTML注释的用途

解释代码：为HTML代码提供说明，解释代码的用途、功能或特定元素的意义。

标记代码块：用于标记特定的代码块，以便将来参考或修改。

临时移除代码：如果不想删除某段代码，但又不希望它出现在页面上，可以将其注释起来。

为开发人员提供指导：如果有某些需要注意的潜在问题或风险，可以使用注释来提醒其他开发人员。

1.4、HTML注释的最佳实践

简短而有意义：注释应该简短而清晰，能够准确地传达代码的含义和目的。

避免冗余：不要为显而易见的代码或默认行为添加注释。

一致性：在团队开发中，应保持注释风格的一致性，以便其他开发人员能够轻松理解。

位于被注释的代码附近：通常，注释应位于被注释的代码之前或之上，以便于阅读和理解。

使用有意义的注释：确保注释提供了有价值的信息，而不是简单的“TODO”或“此处需要修改”。

二、CSS 注释

CSS注释是一种在CSS代码中添加说明和解释的方法，它们不会被浏览器执行或解析，而是被浏览器忽略。CSS注释对于代码的可读性、可维护性和团队协作非常重要。

2.1、CSS注释的语法

单行注释

语法：/* 单行注释内容 */

语法：//

/* 为所有 h1 标签设置 CSS 样式 */

多行注释

/*  
多行注释内容  
可以跨越多行  
*/

这样也是可以的

3.2、CSS注释的用途

解释代码：为CSS代码提供说明，解释代码的用途、功能或特定样式设置的原因。

标记代码块：用于标记特定的代码块，以便将来参考或修改。

禁用代码：如果不想删除某段代码，但又不希望它被执行，可以将其注释起来。

警告其他开发人员：如果有某些需要注意的潜在问题或风险，可以使用注释来提醒其他开发人员。

3.3、CSS注释的最佳实践

简短而有意义：注释应该简短而清晰，能够准确地传达代码的含义和目的。

避免冗余：不要为显而易见的代码或默认行为添加注释。

一致性：在团队开发中，应保持注释风格的一致性，以便其他开发人员能够轻松理解。

位于被注释的代码之前：通常，注释应位于被注释的代码之前，以便于阅读和理解。

使用单行注释或多行注释：对于较短的注释，可以使用单行注释；对于较长的注释或需要跨越多行的注释，应使用多行注释。

3.4、示例

/* 为所有 h1 标签设置 CSS 样式 */  
h1 {  
  color: blue; /* 设置字体颜色为蓝色 */  
  text-align: center; /* 设置对齐方式为居中对齐 */  
}  
  
/* 为所有 p 标签设置 CSS 样式 */  
p {  
  color: red; /* 设置字体颜色为红色 */  
  font-size: 18px; /* 设置字体大小为18像素 */  
}

三、JavaScript 注释

3.1、单行注释

使用//来标记单行注释。这之后的文本将不会被JavaScript引擎执行或解释。

// 这是一个单行注释
var x = 5; // 这个变量的值为5

3.2、多行注释

使用/*开始，并用*/结束来标记多行注释。在这之间的所有文本都不会被JavaScript引擎执行或解释。

/*
这是一个多行注释
可以跨越多行
var y = 10;
*/

四、JSDoc注释

4.1、常用的JSDoc标记

@param：描述函数或方法的参数。包括参数名、参数类型和参数描述。

@returns 或 @return：描述函数或方法的返回值。包括返回值的类型和描述。

@type：描述变量、对象属性或函数返回值的类型。

@description：提供关于注释块的更详细描述。

@example：提供示例代码。

@see：提供参考链接。

4.2、示例

/**  
 * 将两个数字相加，第二个数字可选，默认为0  
 *  
 * @param {number} a 第一个数字  
 * @param {number} [b=0] 第二个数字，默认为0  
 * @returns {number} 两个数字的和  
 */  
function add(a, b = 0) {  
    return a + b;  
}