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.js或者 detail-v2.2.js,有的公司项目的分支管理也按照这样去管理进行迭代开发的
• 假如js和 css压缩文件, 统一以-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命名

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

<button type="button" class="btn btn-primary">Primary</button>

*id和class的命名总规则为： 内容优先,体现为辅., 首先根据内容来命名, 比方 main-nav. 假如根据内容找不到合适的命名, 可以再结合体现来定, 比方 skin-blue（皮肤蓝色）, present-tab(当前标签).

<div class="main-nav"></div><div class="skin-blue"></div><div class="present-tab">当前标签</div>

• id和class 尽量用英文单词命名 . 的确找不到合适的单词时, 可以考虑使用产品的中文拼音, 比方youzan, tuangou. 也可以使用你们公司的前缀,例如:jh-search,jh-tab

<div class="jh-search"></div><div class="jh-tab"></div>

• 在不影响语义的情况下, id和 class名称中可以适当采用英文单词缩写, 比方 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上阅读优秀的开源代码

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