前端：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> https://img-blog.csdnimg.cn/direct/82d56b89f7884422a1e364807eba70fc.png
1.3、HTML注释的用途
解释代码：为HTML代码提供说明，解释代码的用途、功能或特定元素的意义。
标记代码块：用于标记特定的代码块，以便未来参考或修改。
临时移除代码：假如不想删除某段代码，但又不希望它出如今页面上，可以将其注释起来。
为开发人员提供引导：假如有某些必要留意的潜在问题或风险，可以利用注释来提醒其他开发人员。
1.4、HTML注释的最佳实践
简短而故意义：注释应该简短而清晰，可以或许准确地转达代码的寄义和目标。
避免冗余：不要为显而易见的代码或默认活动添加注释。
一致性：在团队开发中，应保持注释风格的一致性，以便其他开发人员可以或许轻松明确。
位于被注释的代码附近：通常，注释应位于被注释的代码之前或之上，以便于阅读和明确。
利用故意义的注释：确保注释提供了有价值的信息，而不是简朴的“TODO”或“此处必要修改”。
二、CSS 注释
CSS注释是一种在CSS代码中添加说明息争释的方法，它们不会被欣赏器执行或解析，而是被欣赏器忽略。CSS注释对于代码的可读性、可维护性和团队协作非常重要。
2.1、CSS注释的语法
单行注释
语法：/* 单行注释内容 */
语法：//
/* 为所有 h1 标签设置 CSS 样式 */
多行注释
/*
多行注释内容
可以跨越多行
*/ 这样也是可以的
https://img-blog.csdnimg.cn/direct/0d70850342544b7fbadac47f6206714e.png
https://img-blog.csdnimg.cn/direct/05bdf90326df43f6bd85587ad5648d86.png
https://img-blog.csdnimg.cn/direct/b659bd44088f4bcba3ee46ec1fe6f08c.png
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} 第二个数字，默认为0
* @returns {number} 两个数字的和
*/
function add(a, b = 0) {
return a + b;
} 五、代码注释规范
代码注释规范是确保代码清晰、可明确和可维护的重要部分。下面是一些常见的代码注释规范：
5.1、注释类型
单行注释：利用//来注释单行内容。
多行注释：利用/* 开始，*/ 结束来注释多行内容。
文档注释（如JSDoc）：对于函数、类、接口等，利用特定的文档注释格式来描述其用法、参数、返回值等信息。
5.2、注释内容
简洁明确：注释应简洁、直接，避免冗长和复杂的句子。
描述性：解释代码的目标、功能、输入、输出以及任何重要的限制或约束。
避免冗余：不要重复代码本身已经表达的内容。
5.3、注释位置
函数/方法上方：解释函数/方法的用途、参数、返回值等信息。
代码块上方：假如代码块执行了复杂的逻辑或算法，可以在其上方添加注释。
变量声明旁边：对于复杂的或具有特定寄义的变量，可以在其旁边添加注释。
关键或复杂代码行旁边：假如某行代码特别关键或难以明确，可以在其旁边添加注释。
5.4、注释格式
一致性：确保在整个项目中利用一致的注释格式。
对齐：注释应该与代码对齐，以增加可读性。
字体和颜色：在某些IDE或编辑器中，可以为注释设置特定的字体和颜色。
5.5、特别注释
TODO：用于标记必要未来完成或改进的代码部分。
FIXME：用于标记必要修复的错误或问题。
HACK：用于标记可能不优雅的办理方案或权宜之计。
5.6、避免过度注释
不要为简朴的、自解释的代码添加注释。
假如代码本身已经很清晰，那么注释可能是多余的。
5.7、更新注释
当代码发生变化时，确保相关的注释也得到更新。
移除不再相关或不再准确的注释。
5.8、文档注释
对于文档注释（如JavaDoc、JSDoc等），应遵循特定的格式和标记规范，以确保生成的文档清晰、完备。
5.9、注释语言
利用简朴、清晰的语言来编写注释。
避免利用复杂的词汇或行业特定的术语，除非这些术语在项目标上下文中是广泛明确的。
5.10、注释的检察
在代码检察中，确保注释得到得当的关注。
查抄注释是否准确、清晰，并与代码保持一致。
遵循这些注释规范可以帮助你编写更清晰、可维护的代码，并进步团队协作的服从。
参考链接
前端代码规范 - 代码注释_前端注释-CSDN博客
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]