模块规范

[chyingp]

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

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的代码