搜索
博主信息
博文 53
粉丝 0
评论 0
访问量 15701
热门教程
更多>
最新下载
更多>
网站特效
网站源码
网站素材
前端模板
CRMEB 开源商城注释规范:多端适配的 PHP 开发必备指南
い独霸天下う
原创
364人浏览过

注释规范

注释的目的:

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

注释的原则:

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

3.1 HTML 文件注释

3.1.1 单行注释

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

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

  • 推荐:
  1. <!-- Comment Text -->
  2. <div>...</div>
  • 不推荐
  1. <div>...</div><!-- Comment Text -->
  2. <div><!-- Comment Text -->
  3. ...
  4. </div>

3.1.2 模块注释

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

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

  • 推荐:
  1. <!-- S Comment Text A -->
  2. <div class="mod_a">
  3. ...
  4. </div>
  5. <!-- E Comment Text A -->
  6. <!-- S Comment Text B -->
  7. <div class="mod_b">
  8. ...
  9. </div>
  10. <!-- E Comment Text B -->
  • 不推荐
  1. <!-- S Comment Text A -->
  2. <div class="mod_a">
  3. ...
  4. </div>
  5. <!-- E Comment Text A -->
  6. <!-- S Comment Text B -->
  7. <div class="mod_b">
  8. ...
  9. </div>
  10. <!-- E Comment Text B -->

3.1.3 嵌套模块注释

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

  1. <!-- S Comment Text -->
  2. <!-- E Comment Text -->

而改用

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

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

  1. <!-- S Comment Text A -->
  2. <div class="mod_a">
  3. <div class="mod_b">
  4. ...
  5. </div>
  6. <!-- /mod_b -->
  7. <div class="mod_c">
  8. ...
  9. </div>
  10. <!-- /mod_c -->
  11. </div>
  12. <!-- E Comment Text A -->

3.2 CSS 文件注释

3.2.1 单行注释

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

  • 推荐:
  1. /* Comment Text */
  2. .jdc {}
  3. /* Comment Text */
  4. .jdc {}
  • 不推荐:
  1. /*Comment Text*/
  2. .jdc {
  3. display: block;
  4. }
  5. .jdc {
  6. display: block;/*Comment Text*/
  7. }

3.2.2 模块注释

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

  • 推荐:
  1. /* Module A
  2. ---------------------------------------------------------------- */
  3. .mod_a {}
  4. /* Module B
  5. ---------------------------------------------------------------- */
  6. .mod_b {}
  • 不推荐:
  1. /* Module A ---------------------------------------------------- */
  2. .mod_a {}
  3. /* Module B ---------------------------------------------------- */
  4. .mod_b {}

3.2.3 文件注释

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

  1. @charset "UTF-8";
  2. /**
  3. * @desc File Info
  4. * @author Author Name
  5. * @date 2015-10-10
  6. */

3.3 JavaScript 文件注释

3.3.1 单行注释

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

  • 推荐:
  1. // is current tab
  2. const active = true
  • 不推荐:
  1. const active = true // is current tab

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

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

3.3.2 多行注释

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

  • 推荐:
  1. /**
  2. * make() returns a new element
  3. * based on the passed-in tag name
  4. */
  5. function make (tag) {
  6. // ...
  7. return element
  8. }
  • 不推荐:
  1. // make() returns a new element
  2. // based on the passed in tag name
  3. function make (tag) {
  4. // ...
  5. return element
  6. }

3.3.3 注释空格

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

  • 推荐:
  1. // is current tab
  2. const active = true
  3. /**
  4. * make() returns a new element
  5. * based on the passed-in tag name
  6. */
  7. function make(tag) {
  8. // ...
  9. return element
  10. }
  • 不推荐:
  1. //is current tab
  2. const active = true
  3. /**
  4. *make() returns a new element
  5. *based on the passed-in tag name
  6. */
  7. function make(tag) {
  8. // ...
  9. return element
  10. }

3.3.4 特殊标记

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

  • // FIXME : 说明问题是什么
  • // TODO : 说明还要做什么或者问题的解决方案
  1. class Calculator extends Abacus {
  2. constructor () {
  3. super ()
  4. // FIXME: 这里不应该使用全局
  5. total = 0
  6. // TODO: 合计应通过选项参数进行配置
  7. this.total = 0
  8. }
  9. }

3.3.5 文档类注释

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

  1. /**
  2. * Book类,代表一个书本.
  3. * @constructor
  4. * @param {string} title - 书本的标题.
  5. * @param {string} author - 书本的作者.
  6. */
  7. function Book (title, author) {
  8. this.title = title
  9. this.author = author
  10. }
  11. Book.prototype = {
  12. /**
  13. * 获取书本的标题
  14. * @returns {string|*}
  15. */
  16. getTitle: function () {
  17. return this.title
  18. },
  19. /**
  20. * 设置书本的页数
  21. * @param pageNum {number} 页数
  22. */
  23. setPageNum: function (pageNum) {
  24. this.pageNum=pageNum
  25. }
  26. }

附件:https://gitee.com/ZhongBangKeJi/CRMEB

附件:https://gitee.com/ZhongBangKeJi/CRMEB

本博文版权归博主所有,转载请注明地址!如有侵权、违法,请联系admin@php.cn举报处理!
全部评论 文明上网理性发言,请遵守新闻评论服务协议
0条评论
关于我们 免责申明 意见反馈 讲师合作 广告合作 最新更新 English
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号 技术交流群
PHP中文网订阅号
每天精选资源文章推送
PHP中文网APP
随时随地碎片化学习
PHP中文网抖音号
发现有趣的

Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号

  • 登录PHP中文网,和优秀的人一起学习!
    全站2000+教程免费学