在js开发前需要的东西(规范)

2018-01-17 本文已影响108人 cbw100

1. 前言

俗话说，无规矩不成方圆，工欲善其事必先利其器。

在进行前端工作快2年时间了，虽然平时写代码会写注释，但是并没有太符合规范，虽然很早就知道可以用eslint来规范代码，还有editorconfig来约束代码风格，但是在平时工作中并没有严格按照这些来做。

直到公司来了一个新同事把这件事提了出来，并在团队中推广。当一个团队慢慢变大时，很有必要统一代码风格和规范。

对于写前端js代码，这里推荐vscode，本文介绍的插件相关的也是vscode的

2. 代码注释规范

2.1 文件开头

对于新建一个文件，有必要写明开发者是谁，注明，好让别人或者同事知道这是谁开发的，有问题能快速定位。对于标明开发者信息的插件，这里介绍一个vscode-fileheader，在vscode上下载安装后，就可以自己配置一下，来快速生成作者信息，在插件下载页面有详细的介绍如何使用。效果如下图：

image.png

2.2 代码注释规范

添加必要的注释，对一个有责任心、有道德模范的前端必须具备的好习惯，可以大大提高代码的可维护性、可读性。
首先熟悉一下html、css、js的注释的写法：
1、HTML注释语法：

<!--注释的内容-->

2、css注释语法

/* 注释内容 */
/* ----------文字样式开始---------- */

3、javaScript注释

//注释内容
/*注释内容*/

接下来是对注释在这几种代码中使用的位置，如何写注释进行总结一下。（根据个人的习惯可能不一样）

1、html注释
使用的位置：
1）一般会使用在一些主要节点标签结束的后边，如：

<div class="wrap">
<div class="main">
...
</div><!--main end-->
<div><!--wrap end-->

2）使用在一些循环的结束的后边，如：

<ul class="list">
    <li>111111</li>
    <li>222222</li>
    <li>333333</li>
</ul><!--list loop-->

这一切都是为了程序在嵌套的时候更加方便、明了。方便了他人同时也就方便了自己。程序嵌套的很乱，到时要你去修改那也是一份挺复杂的工序。

2、css注释
一般会使用在定义某个模块样式的上边，说明这段样式是作用于哪段模块，如：

/*通用 - 评论*/
.comment{...}
/*相册*/
.photo{...}
/*分享*/
.share{...}
/*投票*/
.vote{...}

3、javascript注释
目前脚本、样式的注释格式都有一个已经成文的约定规范，最初是YUI Compressor制定。

/**
* 这里的注释内容【会】被压缩工具压缩
*/
 
/*！
* 这里的注释内容【不会】被压缩工具压缩
* 与上面一个注释块不同的是，第2个*换成了!
*/

其中说到这里说到的压缩工具有YUI Compressor 、Google Closure Compiler、gulp-uglify、grunt-contrib-uglify等，这些压缩工具都支持以上的压缩约定。常常把文件的关键信息放在第2种注释内容里，如文件名称、版本号、作者等。

关于这些关键信息，都由一些关键词和一定的格式来书写。关键词书写格式为：

/**
* @author ydr.me
* @version 1.0
*/

使用@key desc格式来书写，常用的关键词有：

关键词	描述
@auhor	作者
@param	参数
@example	示例
@link	链接
@namespace	命名空间
@requires	依赖模块
@return	返回值
@version	版本号

其中，param关键词的格式为：

/**
* @param {String} 参数描述
*/

常用的js 函数注释举例

/**
 * 函数功能
 * @param 参数
 * @return 返回值
 */

最后，注释也是字符也是会有流量产生。因此当页面发布到正式地址的时候，最好加上一步优化流程。
压缩过程为非逆过程，保证本地是最新的而且带有注释的文件，压缩后上传服务器。服务器端的文件不可用作本地调试用。这个，现在的打包工具都可以解决。

3. editorconfig

editorConfig不是什么软件，而是一个名称为.editorconfig的自定义文件。该文件用来定义项目的编码规范，编辑器的行为会与.editorconfig 文件中定义的一致，并且其优先级比编辑器自身的设置要高，这在多人合作开发项目时十分有用而且必要

有些编辑器默认支持editorConfig，如webstorm；而有些编辑器则需要安装editorConfig插件，如ATOM、Sublime、VS Code等

当打开一个文件时，EditorConfig插件会在打开文件的目录和其每一级父目录查找.editorconfig文件，直到有一个配置文件root=true

EditorConfig的配置文件是从上往下读取的并且最近的EditorConfig配置文件会被最先读取. 匹配EditorConfig配置文件中的配置项会按照读取顺序被应用, 所以最近的配置文件中的配置项拥有优先权

如果.editorconfig文件没有进行某些配置，则使用编辑器默认的设置

常用的配置为:

root = true

[*]
indent_style = tab
indent_size = 2
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
end_of_line = lf
# editorconfig-tools is unable to ignore longs strings or urls
max_line_length = 120

vscode 插件 EditorConfig for VS Code

4. eslint

在React+Babel+Webpack环境中使用ESLint
常用的配置

{
    'root': true,
    'parser': 'babel-eslint',
    'extends': ['standard', 'plugin:react/recommended'],
    'parserOptions': {
        'ecmaVersion': 6,
        'sourceType': 'module',
        'ecmaFeatures': {
            'jsx': true,
            'experimentalObjectRestSpread': true,
            'impliedStrict': true
        }
    },
    'env': {
        'browser': true,
        'node': true,
        'es6': true
    },
    'plugins': ['import', 'react'],
    'rules': {
        'no-console': ['error', {'allow': ['warn', 'error']}], // 禁止conosle 允许console.warn, console.error
        'no-alert': 'error',                                      // 禁止alert, promp, confirm
        'no-empty': ['error', {'allowEmptyCatch': true}],       // 禁止空代码块(catch除外)
        'no-extra-semi': 'error',                                 // 禁止不必要的分号
        'default-case': 'error',                                  // switch语句必须有default
        'dot-notation': 'error',                                  // 尽可能使用点号
        'no-else-return': 'error',                                // 禁止 if 语句中 return 语句之后有 else 块
        'no-empty-function': 'error',                             // 禁止出现空函数
        'radix': 'error',                                         // 强制在parseInt()使用基数参数
        'semi': ['error', 'always'],
        'quotes': ['error', 'single'],
        'indent': ['error', 'tab'],
        'no-tabs': 'off',
        'one-var': 'off',
        'no-mixed-spaces-and-tabs': ['off', 'smart-tabs'],
        'no-extra-parens': 'warn',
        'no-template-curly-in-string': 'off',
        'key-spacing': ['warn', {'beforeColon': false, 'afterColon': true}],
        'keyword-spacing': ['warn', {'before': true, 'after': true}],
        'no-multi-spaces': ['warn', {'ignoreEOLComments': true}],
        'spaced-comment': 'off',
        'comma-dangle': 'off',
        'react/display-name': 'off',
        'react/prop-types': ['warn', {ignore: ['match', 'location', 'history']}],
        'react/self-closing-comp': ['error', {'component': true}],
        'import/no-webpack-loader-syntax': 'off'
    }
}

更多关于eslint 的内容可以看React+Babel+Webpack

vscode 插件 ESLint

5. 相关文章

原文地址: 在js开发前需要的东西(规范)