CRMEB 注释规范:多端适配下的代码可读性提升之道

注释规范

注释的目的:

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

注释的原则:

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

3.1 HTML 文件注释

3.1.1 单行注释

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

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

  • 推荐:
xml 复制代码
<!-- Comment Text -->
<div>...</div>
  • 不推荐
xml 复制代码
<div>...</div><!-- Comment Text -->

<div><!-- Comment Text -->
  ...
</div>

3.1.2 模块注释

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

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

  • 推荐:
xml 复制代码
<!-- 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 -->
  • 不推荐
xml 复制代码
<!-- 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 -->

3.1.3 嵌套模块注释

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

xml 复制代码
<!-- S Comment Text -->
<!-- E Comment Text -->

而改用

xml 复制代码
<!-- /Comment Text -->

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

xml 复制代码
<!-- 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 -->

3.2 CSS 文件注释

3.2.1 单行注释

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

  • 推荐:
arduino 复制代码
/* Comment Text */ 
.jdc {} 

/* Comment Text */ 
.jdc {}
  • 不推荐:
css 复制代码
/*Comment Text*/
.jdc {
  display: block;
}

.jdc {
  display: block;/*Comment Text*/
}

3.2.2 模块注释

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

  • 推荐:
arduino 复制代码
/* Module A
---------------------------------------------------------------- */
.mod_a {}


/* Module B
---------------------------------------------------------------- */
.mod_b {}
  • 不推荐:
arduino 复制代码
/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}

3.2.3 文件注释

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

java 复制代码
@charset "UTF-8";
/**
 * @desc File Info
 * @author Author Name
 * @date 2015-10-10
 */

3.3 JavaScript 文件注释

3.3.1 单行注释

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

  • 推荐:
arduino 复制代码
// is current tab
const active = true
  • 不推荐:
arduino 复制代码
const active = true // is current tab

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

  • 推荐:
lua 复制代码
function getType () {  
  console.log('fetching type...')

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

3.3.2 多行注释

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

  • 推荐:
php 复制代码
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...

  return element
}
  • 不推荐:
php 复制代码
// make() returns a new element
// based on the passed in tag name
function make (tag) {
  // ...

  return element
}

3.3.3 注释空格

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

  • 推荐:
php 复制代码
// is current tab
const active = true

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}
  • 不推荐:
php 复制代码
//is current tab
const active = true

/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}

3.3.4 特殊标记

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

  • // FIXME : 说明问题是什么
  • // TODO : 说明还要做什么或者问题的解决方案
scala 复制代码
class Calculator extends Abacus {
  constructor () {
    super ()

      // FIXME: 这里不应该使用全局
      total = 0

      // TODO: 合计应通过选项参数进行配置
      this.total = 0
  }
}

3.3.5 文档类注释

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

javascript 复制代码
/**
 * 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
  }
}

附件:gitee.com/ZhongBangKe...

相关推荐
jingling5552 小时前
解决微信小程序真机调试中访问本地接口 localhost:8080 报错
前端·微信小程序·小程序
en-route2 小时前
使用 Flask 构建 Web 应用:静态页面与动态 API 访问
前端·python·flask
IT_陈寒2 小时前
Vite 5年迭代揭秘:3个核心优化让你的项目构建速度提升200%
前端·人工智能·后端
怎么吃不饱捏3 小时前
vue3+vite,引入阿里巴巴svg图标,自定义大小颜色
前端·javascript·vue.js
无敌最俊朗@3 小时前
MQTT 关键特性详解
java·前端·物联网
JAVA学习通3 小时前
微服务项目->在线oj系统(Java-Spring)----[前端]
java·开发语言·前端
excel3 小时前
Vue3 响应式系统核心执行器:Reactive Effect 与依赖调度机制
前端
南玖i5 小时前
vue3 通过 Vue3DraggableResizable实现拖拽弹窗,可修改大小
前端·javascript·vue.js
excel5 小时前
Web发展与Vue.js导读
前端
YAY_tyy5 小时前
Three.js 开发实战教程(五):外部 3D 模型加载与优化实战
前端·javascript·3d·three.js