JavaScript企业级编程规范(1)-文件命名-注释规范-id与class

前言

好的代码是有生命力的,程序是写给人读的,顺便在机器上跑一下

当你在阅读别人的代码时,据说评判一个项目的好坏,就是看阅读代码人说脏话程度

无注释,无文档,命名千奇百怪等等,对于后来者,极其痛苦,其实个人觉得一个非常好的产品,一手代码非常重要,既是标准,往往又是参照

工作中,往往令人尊敬的,就是代码的产出,少bug,写得又好又快,毫无疑问是团队中最受敬仰的,而好的命名往往可以看出一个程序员的功力

做一个自我要求高一点的工程师,而不止于完成任务。从代码规范做起,什么是好代码,可读性好,可维护性高.易拓展.少bug,高质量,这些硬技能并非一蹴而就.非一日之功.

人人都喜欢和聪明人一起工作,我们无法要求别人怎么样,但可以要求自己.
无论团队人数多少,代码应该同出一门。下面这些规范不是硬性规定,但不妨可以作为参照,向大厂看齐~

文件夹(项目)命名规范

  • 项目名全部采用小写方式, 以中划线分隔。 比如: my-project-name, 例如:ant-design-pro,ant-design-colors等,当项目名称有多个字符时,不是说驼峰命名法myProjectName不行,用横杠中划线进行连接,已经是约定俗成的习惯,一定要向大厂的标准看齐
    下面以阿里的ant design Team团队出品为例
    目录文件命名.png

子项目录名

当有复数结构时,要采用复数命名法,如有多个单词时,用横杠连接,比如说: scripts, styles, images, data-models

文件夹目录名称.png

值得一提的是:JavaScript文件的存放的文件夹放在Web应⽤用目录中的components文件夹或其以业务组件,应用小写标识命名子文件夹
文件夹功能命名.png

JavaScript文件命名

  • 所有的JavaScript文件均以.js结尾
  • 所有js文件名,当遇到多个单词组成时,采用中划线连接方式,比如说: 比如检查commit提交文件, check-commit.js,首字母小写,如下所示
  • 当出现版本号时, 需要用字母v做为前缀, 小版本号用点号(.)隔开, global-v8.jsdetail-v2.2.js,有的公司项目的分支管理也按照这样去管理进行迭代开发的
  • 如果jscss压缩文件, 统一以-min 结尾, 比如源码文件为 react.js, 压缩后为 react-min.js,一般线上坏境端的,为了减少体积,一些额外的类库可以选用压缩版本的
check-commit.js // ✓ ok,值得推荐
Check-Commit.js // ✗ avoid,避免,不是不可以,如果项目里都是驼峰,那就驼峰命名,并且首字母小写,文件名字统一
cc.js // ✗ avoid,不要简写,这是什么意思的
javascript文件命名.png

CSS,LESS,SCSS文件命名

参照项目命名规则,当遇到多个单词组成时,采用中划线连接方式,比如说:retina-sprites.scss

HTML文件命名

同样参照项目命名,多个单词组成时,采用中划线连接方式,比如说: error-report.html

图片资源命名

同样参照项目命名,多个单词组成时,采用中下划线连接方式,input_bg_search_default@2x.png,组件类别功能状态@2x.png,对应的中文是:输入框背景色搜索默认,这种命名方式不是硬性的,应当是灵活的,语义化,最棒的就是让人一看名字就能理解这图片代表的含义

上面的命名规范,都适用于html, css, js, png, gif, jpg,等前端维护的所有文件类型和相关目录.

对于文件以及目录或者是变量的命名,的确是一个令人头疼的问题,但对于程序员来说,是问题,肯定有人想办法去解决:推荐一个变量命名神器网站[codeIf](https://unbug.github.io/codelf/,当然也可以在vscode插件市场中搜索CodeIf,直接安装就可以了,使用也很简单,选中变量单词右键codeIf就可以进入这个变量命名神器网站的

codeIf变量命名神器网站.png

有了它,真的可以减少不少变量命名的痛苦.
codeIf官方github网站

注释规范

涉及到文档注释,单行注释与多行注释,变量,语句,函数注释

文档注释

当针对整个文件的注释,必须放在js⽂文件的开头,注释顺序及内容如下,这个不是硬性规定的,具体与自己的公司,项目注释规范而定

  • 版权信息,如:Copyright © 2020, xxx company. All rights reserved.
  • 产品及模块信息
  • 创建日期 日期格式为:YYYY-MM-DD。
  • 作者信息 格式为花名+工号,没有工号直接写自己昵称即可
  • 描述信息。用于简单介绍该js⽂文件的功能,准确简练就好
    如下所示:
/*
 * @LineStart: -------------------------------------------
 * @Copyright: © 2020, itclanCoder. All rights reserved.
 * @LineEnd: ----------------------------------------------
 * @Product: h5活动页
 * @Mode Name: 转盘抽奖
 * @Autor: vxPublic:itclanCoder
 * @Date: 2020-02-19 16:42:51
 * @Version: xxx.v1.0
 * @LastEditors: 川川
 * @LastEditTime: 2020-02-24 11:14:41
 * @Description: 转盘抽象公共js模块的封装
 */

至于这个代码注释配置,很多代码编辑器都有相应的插件和快捷键配置:这里以vscode为例,
在vscode的应用商店中搜索安装koroFileHeader这个插件即可,具体配置可参考:VsCode插件,自动生成注释koroFileHeader

如果你实在不知道怎么弄,也可以加我微信搜索suibichuanji,可手把手教你,不过对于一个写代码小伙伴来说,玩插件,配置之类的,应该不是什么问题

单行注释

  • 双斜线后,必须跟注释内容保留一个空格
  • 可独占一行, 前边不许有空行, 缩进与下一行代码保持一致
  • 可位于一个代码行的末尾,注意这里的格式
    如下代码:
// Good,圆括号后有一空格
if  (condition)  {
    // 如果你在此处完成,则所有安全检查都通过了
    allowed();
}

var sName = "itclanCoder";    // 双斜线距离分号四个空格,双斜线后始终保留一个空格

多行注释

  • 最少三行, 格式如下所示
  • 前边留空一行
/*
 *  注释内容与星标前保留一个空格
 */

这里,建议在以下情况下使用多行注释:

  • 难于理解的代码段
  • 可能存在错误的代码段
  • 浏览器特殊的HACK代码
  • 业务逻辑强相关的代码

变量语句注释

针对变量中的语句注释,可以放在变量定义行和语句行的上一行,使用javaScript标准的单行注释,如下所示
// 获取窗口的宽度

var nWidth = widow.screen.width;

在开发中,对于不改变的常量用大写单词表示,多个单词之间用下划线进行连接

/* 监听表单输入 */
const HANDLE_INPUT_VALUE = 'handle_input_value' 

函数注释
针对某个函数的注释,必须放在函数定义行的上一行,注释内容包括:

  • 函数功能说明,介绍该函数的功能
  • 参数列表,各个参数的说明,如果没有参数,该内容可以省略
  • 返回值,返回值说明,如果没有返回值,该内容可以省略
/**
* 函数功能详细 打开模态对话框
* @param [参数1] [参数说明]
* @param [参数2] [参数说明]
* @return [返回值说明]
*/
function openModelDialog(url, winName, width, height) {
}

Id与class命名

  • 保持 Classid命名为全小写,可以使用短划线(不要使用下划线和 camelCase驼峰式命名,这个不是硬性规定,看公司小伙伴的代码风格,但至少代码风格保持一致)。短划线应该作为相关类的自然间断。(例如,.btn.btn-primary,可参考bootstrap的命名风格
<button type="button" class="btn btn-primary">Primary</button>

*idclass的命名总规则为: 内容优先,表现为辅., 首先根据内容来命名, 比如 main-nav. 如果根据内容找不到合适的命名, 可以再结合表现来定, 比如 skin-blue(皮肤蓝色), present-tab(当前标签).

<div class="main-nav"></div>
<div class="skin-blue"></div>
<div class="present-tab">当前标签</div>
  • idclass 尽量用英文单词命名 . 确实找不到合适的单词时, 可以考虑使用产品的中文拼音, 比如youzan, tuangou. 也可以使用你们公司的前缀,例如:jh-search,jh-tab
<div class="jh-search"></div>
<div class="jh-tab"></div>
  • 在不影响语义的情况下, idclass名称中可以适当采用英文单词缩写, 比如 col, nav, hd, bd, ft 等, 但切忌自造缩写,例如:aa,bb,cc(不要这么写)
布局类:header, footer, container, main, content, aside, page, section
包裹类:wrap, inner
区块类:region, block, box
结构类:hd, bd, ft, top, bottom, left, right, middle, col, row, grid, span
列表类:list, item, field
主次类:primary, secondary, sub, minor
大小类:s, m, l, xl, large, small
状态类:active, current, checked, hover, fail, success, warn, error, on, off
导航类:nav, prev, next, breadcrumb, forward, back, indicator, paging, first, last
交互类:tips, alert, modal, pop, panel, tabs, accordion, slide, scroll, overlay,
星级类:rate, star
分割类:group, seperate, divider
等分类:full, half, third, quarter
表格类:table, tr, td, cell, row
图片类:img, thumbnail, original, album, gallery
语言类:cn, en
论坛类:forum, bbs, topic, post
方向类:up, down, left, right
其他语义类:btn, close, ok, cancel, switch; link, title, info, intro, more, icon; form, label, search, contact, phone, date, email, user; view, loading...
  • id的优先级要高于class,class是为高可复用组件设计的,理论上他们应处在第一位。Id更加具体而且应该尽量少使用(例如, 页内书签),它是唯一的
<a id="..." class="..."  href="#">
   阅读原文
</a>

结语

本小节主要介绍了javaScript中编程规范的8个点,文件夹项目命名规范,子项目目录名,javaScript文件名,css,less,sass,html,图片资源,注释规范,id与class命名

以上列出的规范并不是硬性的,遵从自己项目的规范就好,写出让人看得懂的代码

个人觉得最佳学习方式,就是参考学习厉害的人的代码,可以在github上阅读优秀的开源代码

提升自己写代码规范的档次,限于篇幅,更多内容见下篇