前端代码规范-注释规范

简介: 注释规范

注释规范

注释的目的:

  • 提高代码的可读性,从而提高代码的可维护性

注释的原则:

  • 如无必要,勿增注释 ( As short as possible )
  • 如有必要,尽量详尽 ( As long as necessary )

HTML 文件注释

单行注释

一般用于简单的描述,如某些状态描述、属性描述等。

注释内容前后各一个空格字符,注释位于要注释代码的上面,单独占一行。

  • 推荐:
<!-- Comment Text -->
<div>...</div>
AI 代码解读
  • 不推荐:
<div>...</div><!-- Comment Text -->

<div><!-- Comment Text -->
  ...
</div>
AI 代码解读

模块注释

一般用于描述模块的名称以及模块开始与结束的位置。

注释内容前后各一个空格字符, <!-- S Comment Text --> 表示模块开始, <!-- E Comment Text --> 表示模块结束,模块与模块之间相隔一行。

  • 推荐:
<!-- S Comment Text A -->    
<div class="mod_a">
  ...
</div>
<!-- E Comment Text A -->
    
<!-- S Comment Text B -->    
<div class="mod_b">
  ...
</div>
<!-- E Comment Text B -->
AI 代码解读
  • 不推荐:
<!-- S Comment Text A -->
<div class="mod_a">
  ...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B -->    
<div class="mod_b">
  ...
</div>
<!-- E Comment Text B -->
AI 代码解读

嵌套模块注释

当模块注释内再出现模块注释的时候,为了突出主要模块,嵌套模块不再使用。

<!-- S Comment Text -->
<!-- E Comment Text -->
AI 代码解读

而改用

<!-- /Comment Text -->
AI 代码解读

注释写在模块结尾标签底部,单独一行。

<!-- S Comment Text A -->
<div class="mod_a">
        
    <div class="mod_b">
        ...
    </div>
    <!-- /mod_b -->
        
    <div class="mod_c">
        ...
    </div>
    <!-- /mod_c -->
        
</div>
<!-- E Comment Text A -->
AI 代码解读

CSS 文件注释

单行注释

注释内容第一个字符和最后一个字符都是一个空格字符,单独占一行,行与行之间相隔一行。

  • 推荐:
/* Comment Text */ 
.jdc {} 
/* Comment Text */ 
.jdc {}
AI 代码解读
  • 不推荐:
/*Comment Text*/
.jdc {
  display: block;
}
.jdc {
  display: block;/*Comment Text*/
}
AI 代码解读

模块注释

注释内容第一个字符和最后一个字符都是一个空格字符,/* 与 模块信息描述占一行,多个横线分隔符 -*/ 占一行,行与行之间相隔两行。

  • 推荐:
/* Module A
---------------------------------------------------------------- */
.mod_a {}
/* Module B
---------------------------------------------------------------- */
.mod_b {}
AI 代码解读
  • 不推荐:
/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}
AI 代码解读

文件注释

在样式文件编码声明 @charset 语句下面注明页面名称、作者、创建日期等信息。

@charset "UTF-8";
/**
 * @desc File Info
 * @author Author Name
 * @date 2015-10-10
 */
AI 代码解读

JavaScript 文件注释

单行注释

单行注释使用 //,注释应单独一行写在被注释对象的上方,不要追加在某条语句的后面。

  • 推荐:
// is current tab
const active = true
AI 代码解读
  • 不推荐:
const active = true // is current tab
AI 代码解读

注释行的上方需要有一个空行(除非注释行上方是一个块的顶部),以增加可读性。

  • 推荐:
function getType () {  
  console.log('fetching type...')
  
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}
AI 代码解读
// 注释行上面是一个块的顶部时不需要空行
function getType () {  
  // set the default type to 'no type'
  const type = this.type || 'no type'            
  return type
}
AI 代码解读
  • 不推荐:
function getType () {  
  console.log('fetching type...')
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}
AI 代码解读

多行注释

多行注释使用 /** ... */,而不是多行的 //

  • 推荐:
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...
  return element
}
AI 代码解读
  • 不推荐:
// make() returns a new element
// based on the passed in tag name
function make (tag) {
  // ...
  return element
}
AI 代码解读

注释空格

注释内容和注释符之间需要有一个空格,以增加可读性。eslint: spaced-comment

  • 推荐:
// is current tab
const active = true
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...
  return element
}
AI 代码解读
  • 不推荐:
//is current tab
const active = true
/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...
  return element
}
AI 代码解读

特殊标记

有时我们发现某个可能的 bug,但因为一些原因还没法修复;或者某个地方还有一些待完成的功能,这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。常用的特殊标记有两种:

  • // FIXME : 说明问题是什么
  • // TODO : 说明还要做什么或者问题的解决方案
class Calculator extends Abacus {
  constructor () {
    super ()
      // FIXME: shouldn’t use a global here
      total = 0
      // TODO: total should be configurable by an options param
      this.total = 0
  }
}
AI 代码解读

文档类注释

文档类注释,如函数、类、文件、事件等;都使用 jsdoc 规范。

/**
 * Book类,代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book (title, author) {
  this.title = title
  this.author = author
}
Book.prototype = {
  /**
   * 获取书本的标题
   * @returns {string|*}
   */
  getTitle: function () {
    return this.title
  },
  /**
   * 设置书本的页数
   * @param pageNum {number} 页数
   */
  setPageNum: function (pageNum) {
    this.pageNum=pageNum
  }
}
AI 代码解读

注释工具

ESLint 是当下最流行的 JS 代码检查工具,ESLint 中有一些注释相关的规则,用户可选择开启:

  • valid-jsdoc
  • require-jsdoc
  • no-warning-comments
  • capitalized-comments
  • line-comment-position
  • lines-around-comment
  • multiline-comment-style
  • no-inline-comments
  • spaced-comment
目录
打赏
0
1
0
0
3
分享
相关文章
|
30天前
|
【05】flutter完成注册页面完善样式bug-增加自定义可复用组件widgets-严格规划文件和目录结构-规范入口文件-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草央千澈
【05】flutter完成注册页面完善样式bug-增加自定义可复用组件widgets-严格规划文件和目录结构-规范入口文件-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草央千澈
121 75
【05】flutter完成注册页面完善样式bug-增加自定义可复用组件widgets-严格规划文件和目录结构-规范入口文件-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草央千澈
前端项目代码规范工具 (ESLint. Prettier. Stylelint. TypeScript)
前端项目代码规范工具 (ESLint. Prettier. Stylelint. TypeScript)
174 4
前端研发链路之代码规范
大家好,我是徐徐。本文将探讨前端研发链路中的代码规范,包括业界流行规范、CSS命名规范和相关工具。通过保持代码整洁和一致性,不仅能提高团队协作效率,还能减少错误,提升开发质量。文中详细对比了几种常见的代码规范和工具,如 Airbnb Style Guide、BEM、Eslint 和 Prettier,并展望了未来代码规范的发展趋势。希望对大家有所帮助。
140 1
前端研发链路之代码规范
如何从零到一建立前端规范
【10月更文挑战第6天】
112 2
如何清理 docker 磁盘空间+修改 Gitea 服务器的 Webhook 设置+前端一些好学好用的代码规范-git hook+husky + commitlint
如何清理 docker 磁盘空间+修改 Gitea 服务器的 Webhook 设置+前端一些好学好用的代码规范-git hook+husky + commitlint
61 5
前端代码规范和质量是确保项目可维护性、可读性和可扩展性的关键(三)
前端代码规范和质量是确保项目可维护性、可读性和可扩展性的关键(三)
65 0
前端代码规范和质量是确保项目可维护性、可读性和可扩展性的关键(二)
前端代码规范和质量是确保项目可维护性、可读性和可扩展性的关键(二)
92 0
前端代码规范和质量是确保项目可维护性、可读性和可扩展性的关键(一)
前端代码规范和质量是确保项目可维护性、可读性和可扩展性的关键(一)
107 0

热门文章

最新文章

  • 1
    【11】flutter进行了聊天页面的开发-增加了即时通讯聊天的整体页面和组件-切换-朋友-陌生人-vip开通详细页面-即时通讯sdk准备-直播sdk准备-即时通讯有无UI集成的区别介绍-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草Alex
    12
  • 2
    【08】flutter完成屏幕适配-重建Android,增加GetX路由,屏幕适配,基础导航栏-多版本SDK以及gradle造成的关于fvm的使用(flutter version manage)-卓伊凡换人优雅草Alex-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草Alex
    23
  • 3
    详解智能编码在前端研发的创新应用
    16
  • 4
    巧用通义灵码,提升前端研发效率
    14
  • 5
    智能编码在前端研发的创新应用
    9
  • 6
    【07】flutter完成主页-完成底部菜单栏并且做自定义组件-完整短视频仿抖音上下滑动页面-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草央千澈
    12
  • 7
    大前端之前端开发接口测试工具postman的使用方法-简单get接口请求测试的使用方法-简单教学一看就会-以实际例子来说明-优雅草卓伊凡
    25
  • 8
    VSCode AI提效工具,通义灵码前端开发体验
    61
  • 9
    【09】flutter首页进行了完善-采用android studio 进行真机调试开发-增加了直播间列表和短视频人物列表-增加了用户中心-卓伊凡换人优雅草Alex-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草Alex
    7
  • 10
    以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
    12
  • 1
    【01】鸿蒙实战应用开发-华为鸿蒙纯血操作系统Harmony OS NEXT-项目开发实战-优雅草卓伊凡拟开发一个一站式家政服务平台-前期筹备-暂定取名斑马家政软件系统-本项目前端开源-服务端采用优雅草蜻蜓Z系统-搭配ruoyi框架admin后台-全过程实战项目分享-从零开发到上线
    25
  • 2
    VSCode AI提效工具,通义灵码前端开发体验
    61
  • 3
    开箱即用的GO后台管理系统 Kratos Admin - 前端权限
    4
  • 4
    以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
    34
  • 5
    大前端之前端开发接口测试工具postman的使用方法-简单get接口请求测试的使用方法-简单教学一看就会-以实际例子来说明-优雅草卓伊凡
    66
  • 6
    【2025优雅草开源计划进行中01】-针对web前端开发初学者使用-优雅草科技官网-纯静态页面html+css+JavaScript可直接下载使用-开源-首页为优雅草吴银满工程师原创-优雅草卓伊凡发布
    31
  • 7
    巧用通义灵码,提升前端研发效率
    97
  • 8
    【11】flutter进行了聊天页面的开发-增加了即时通讯聊天的整体页面和组件-切换-朋友-陌生人-vip开通详细页面-即时通讯sdk准备-直播sdk准备-即时通讯有无UI集成的区别介绍-开发完整的社交APP-前端客户端开发+数据联调|以优雅草商业项目为例做开发-flutter开发-全流程-商业应用级实战开发-优雅草Alex
    148
  • 9
    详解智能编码在前端研发的创新应用
    107
  • 10
    智能编码在前端研发的创新应用
    84