HOME
NAVIGATION

前端代码规范(1)——代码检查、注释、命名

前端代码规范合集

0.代码检查

对于比较宽松自由的编程语言来说,严格遵循编码规范和格式化风格指南就显得极为重要。遵循规范固然很好,但是有自动化流程来确保其执行情况,岂不更佳。

对于 JavaScript,建议使用JSLintJSHint

1.文件/资源命名

在 web 项目中,所有的文件名应该都遵循同一命名约定。以可读性而言,减号(-)是用来分隔文件名的不二之选。同时它也是常见的 URL 分隔符:

example.com/blog/my-blog-entry or//s.example.com/images/big-black-background.jpg)

所以理所当然的,减号应该也是用来分隔资源名称的好选择。

  • 确保文件命名总是以字母开头而不是数字。而以特殊字符开头命名的文件,一般都有特殊的含义与用处(比如 compass(Compass 是一个基于 Sass 开源的 CSS 框架,而 Sass 是一个非常流行的 CSS 预编译器。) 中的下划线就是用来标记跳过直接编译的文件用的)。
  • 资源的字母名称必须全为小写,这是因为在某些对大小写字母敏感的操作系统中,当文件通过工具压缩混淆后,或者人为修改过后,大小写不同而导致引用文件不同的错误,很难被发现。
  • 还有一些情况下,需要对文件增加前后缀或特定的扩展名(比如 .min.js, .min.css),抑或一串前缀(比如 3fa89b.main.min.css)。这种情况下,建议使用点分隔符来区分这些在文件名中带有清晰意义的元数据。

2.协议

不要指定引入资源所带的具体协议。

当引入图片或其他媒体文件,还有样式和脚本时,URLs 所指向的具体路径,不要指定协议部分(http:, https:),除非这两者协议都不可用。不指定协议使得 URL 从绝对的获取路径转变为相对的,在请求资源协议无法确定时非常好用,而且还能为文件大小节省几个字节。

不推荐:

src="http://cdn.com/foundation.min.js"

推荐

src="//cdn.com/foundation.min.js"

注:在html或css中都适用

3.命名

命名的方法通常有以下几类:

命名法说明
  1. camel命名法,形如thisIsAnApple
  2. pascal命名法,形如ThisIsAnApple
  3. 下划线命名法,形如this_is_an_apple
  4. 中划线命名法,形如this-is-an-apple
根据不同类型的内容,必须严格采用如下的命名法: 
  • 变量名:必须使用camel命名法
  • 参数名:必须使用camel命名法
  • 函数名:必须使用camel命名法
  • 方法/属性:必须使用camel命名法
  • 私有(保护)成员:必须以下划线_开头
  • 常量名:必须使用全部大写的下划线命名法,如IS_DEBUG_ENABLED
  • 类名:必须使用pascal命名法
  • 枚举名:必须使用pascal命名法
  • 枚举的属性:必须使用全部大写的下划线命名法
  • 命名空间:必须使用camel命名法
语义:命名同时还需要关注语义,如:
  • 变量名应当使用名词;
  • boolean类型的应当使用is、has等起头,表示其类型;
  • 函数名应当用动宾短语;
  • 类名应当用名词。

4.注释

注释要尽量简单,清晰明了。着重注释的意思,对不太直观的部分进行注解:

此外,JavaScript 的注释有两种"//" 和"/* .... */",建议"//"用作代码行注释,"/* .... */"形式用作对整个代码段的注销,或较正式的声明中,如函数参数、功能、文件功能等的描述中:

编写自解释代码只是一个传说,没有任何代码是可以完全自解释的。而代码注释,则是永远也不嫌多。

当你写注释时一定要注意:

不要写你的代码都干了些什么,而要写你的代码为什么要这么写,背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。