Web前端之路深究JavaScript

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

2020-04-04  本文已影响0人  itclanCoder

前言

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

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

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

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

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

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

文件夹(项目)命名规范

子项目录名

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

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

JavaScript文件命名

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⽂文件的开头，注释顺序及内容如下，这个不是硬性规定的，具体与自己的公司,项目注释规范而定

/*
 * @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";    // 双斜线距离分号四个空格，双斜线后始终保留一个空格

多行注释

/*
 *  注释内容与星标前保留一个空格
 */

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

变量语句注释

针对变量中的语句注释,可以放在变量定义行和语句行的上一行,使用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命名

<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>

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

布局类：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...

<a id="..." class="..."  href="#">
   阅读原文
</a>

结语

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

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

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

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

上一篇 下一篇

猜你喜欢

热点阅读