前端模块规范 - 文章教程

前端模块规范

发布于 2021-08-09 字数 5494 浏览 948 评论 0

今晚跟团队的小伙伴们碰了下项目中的前端模块规范,这里备忘下,主要包含几点内容

  1. 模块依赖声明
  2. 模块常用调用 example
  3. API 注释
  4. 变量、函数命名规范

模块整体概览

首先来个整体的文件概览,后面会逐项强调下上面说到的几点

/**
 * @fileoverview 前端模块规范的范例,主要注意的几点内容
 *                  1、模块依赖声明
 *                  2、模块常见调用example
 *                  3、API注释
 * @author 程序猿小卡
 * @date 2014.04.02
 * @example
 *      1、显示登陆弹窗
 *      Login.show({
 *          parentNode: document.body,  // 父节点
 *          onClose: function(){}   // 弹窗关闭时的回调方法
 *      });
 *      2、关闭登陆弹窗
 *      Login.hide();
*/
(function (root, factory) {

    // 模块规范之:依赖声明
    if (typeof define === 'function' && define.amd) {
        // @备注 模块的兼容性写法,这里为支持AMD规范的写法,其中,DB为依赖模块
        define(['DB'], factory);
    } else {
        // @备注 不支持AMD的写法,直接将全局模块DB作为依赖的模块参数传入
        root['Login'] = factory(root['DB']);
    }
}(this, function (DB) {

    // 模块规范之:变量命名
    var _isShow = false;    // 私有变量,以下划线 _ 开头
    var MAX_HEIGHT = 400;   // 常量,字母全大写,以下划线 _ 连接

    /**
     * @ignore
     * @description 模块规范之:内部私有方法声明 
     *              1、不用下划线开头
     *              2、驼峰命名
     */
    function getRandomId(){

    }

    /**
     * @namespace
     */
    var exports = {
        /**
         * @description 显示登录框
         * @param {Object} options 配置参数
         * @param {DOMElement} options.parentNode 父节点
         * @param {Function} options.onClose 弹窗关闭后的回调方法
         * @return undefined
        */
        show : function(options){

            // 模块规范之:方法内部变量
            var idOfWin = 'login_' + (new Date() - 0);  // 方法内部的局部变量,普通变量命名规则即可,驼峰命名
            var $container = $(options.parentNode); // jQuery对象,以$开头

            // 具体实现细节略过...
        },
        /**
         * @description 隐藏登录框
         * @return undefined
        */
        hide: function(){
            // 具体实现细节略过
        }
    };

    return exports;

}));

依赖声明

有的项目用到 requirejs 进行模块的依赖管理,而有的项目没有。针对这个问题,下面是个兼容的依赖声明解决方案(非原创)

(function (root, factory) {
  // 模块规范之:依赖声明
  if (typeof define === 'function' && define.amd) {
      // @备注 模块的兼容性写法,这里为支持AMD规范的写法,其中,DB为依赖模块
      define(['DB'], factory);
  } else {
      // @备注 不支持AMD的写法,直接将全局模块DB作为依赖的模块参数传入
      root['Login'] = factory(root['DB']);
  }
}(this, function (DB) {

  var exports = {
      // 各种方法
  };

  return exports;
}));

模块常见调用 demo

一个模块对外暴露的接口可能有很多个,但常用的一般就那么几个。在完善API注释的情况下,如果能够在文件头提供常见的调用示例,那会节省模块调用者不少的时间。这个也不费事,就几行注释搞定的事情。

 * @example
 *      1、显示登陆弹窗
 *      Login.show({
 *          parentNode: document.body,  // 父节点
 *          onClose: function(){}   // 弹窗关闭时的回调方法
 *      });
 *      2、关闭登陆弹窗
 *      Login.hide();
*/

API 注释

接口注释的重要性不用强调了,这块业界也已经有了比较成熟的规范,可以参考 文档,这里只贴个简单的例子

/**
 * @description 显示登录框
 * @param {Object} options 配置参数
 * @param {DOMElement} options.parentNode 父节点
 * @param {Function} options.onClose 弹窗关闭后的回调方法
 * @return undefined
*/
show : function(options){

    // 模块规范之:方法内部变量
    var idOfWin = 'login_' + (new Date() - 0);  // 方法内部的局部变量,普通变量命名规则即可,驼峰命名
    var $container = $(options.parentNode); // jQuery对象,以$开头

    // 具体实现细节略过...
},

变量、函数命名规范

老生长谈的东西,没有固定标准,只有推荐规范,具体要看符不符合项目、团队实际。现在暂定的有

  • 模块私有变量:以下划线开头,比如 _isShow
  • 模块常量:字母全大写,以下划线连接,如 MAX_HEIGHT
  • 模块内部方法:驼峰命名,不以下划线开头,如 getRandomId
  • 模块对外方法:驼峰命名,不以下划线开头,如 show
  • 模块方法内的变量:驼峰命名,不以下划线开头,如 idOfWin
  • jQuery 对象:以 $ 开头进行区分,比如 $container

例子如下:

// 模块规范之:变量命名
var _isShow = false;    // 私有变量,以下划线 _ 开头
var MAX_HEIGHT = 400;   // 常量,字母全大写,以下划线 _ 连接

// 模块规范之:内部私有方法声明 
function getRandomId(){

}

var exports = {

    show : function(options){

        // 模块规范之:方法内部变量
        var idOfWin = 'login_' + (new Date() - 0);  // 方法内部的局部变量,普通变量命名规则即可,驼峰命名
                   // 模块规范之:jQuery对象
        var $container = $(options.parentNode); // jQuery对象,以$开头

        // 具体实现细节略过...
    }
};

各种标记

  • @todo review casperchen 2014.06.21:需要 review 的代码

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2512 文章
30 评论
82839 人气
更多

推荐作者

qianbiandeboy

文章 0 评论 0

少女净妖师

文章 2 评论 0

zangqw

文章 0 评论 0

qq_7HKsl

文章 0 评论 0

伪装你

文章 1 评论 0