出于整个团队代码可读性、可维护性考量,有必要约定一套基本规范(包括代码命名、基础设施、提交日志、对外文档、测试等方面),供各团队都能参考,从而提升项目可持续性发展,也便于成员之间,能很好提升代码 CoverReview 效率等。鉴于此,有将近些年积淀的些许经验,整理成文,希望可以为追求“高效”工作的朋友们,带来一些参考性意见。

前端项目开发规范意见

温馨提醒npm 是前端开发广泛使用的包管理工具,它让 JavaScript 开发者分享、复用代码更方便。鉴于此,每位有经验的前端开发者,都应该对 npmyarnnpx 等工具,以及 package.jsonyarn.lock 等文件,有详尽的了解,如此才能便捷且更大限度的提升效率。先前也因未能了解其全貌,时有掣肘,故而总结了相关文章,如:Npm vs Yarn 之备忘详单前端利器之 npx 使用纪要关乎 package.json 的详细介绍等;如果朋友们有更多实用玩法,欢请不吝分享。

『有则推荐』: 自 2017 年初,就有开始利用闲余时光,打磨个人最新作品——「倾城之链」 ,有意将其打造成优良开放型平台,旨在云集全球优秀网站,让您更为便捷地探索互联网中那更广阔的世界;在这里,您可以轻松发现学习分享更多有用有趣的事物。目前仍在不断迭代、优化中,如果您对此感兴趣,不妨先尝试一下: 「倾城之链」;亦十分欢迎提出您宝贵意见或建议(亦可通过微信扫,描如下小程序码进行体验)。 (Upade@2020-05-01 于深圳.南山)。

小程序码 - 倾城之链

各项配置

显而易见,工具能辅助人发现很多潜在问题;非常必要引入依赖:huskylint-stagedeslintprettier,使得可以从流程上,保证项目的代码风格统一,规避部分错误,且不造成冲突;具体配置,可参考如下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
"scripts": {
"watcher": "onchange \"src/**/**/*.{js,css,scss,vue}\" -- prettier --write {{changed}}",
"prettier": "prettier --write \"src/**/**/*.{js,css,scss,vue}\"",
"eslint-fix": "eslint src/**/**/*.vue --fix",
"precommit-msg": "echo '🐉 Start pre-commit checks...' && exit 0",
},
"eslintConfig": {
"root": true,
"env": {
"node": true,
"es6": true
},
"rules": {
"no-console": 0,
"no-useless-escape": 0
// ......
},
"plugins": [],
"extends": [
"plugin:vue/essential",
"plugin:prettier/recommended",
"eslint:recommended"
],
"parserOptions": {
"parser": "babel-eslint"
}
},
"prettier": {
"singleQuote": true,
"semi": false,
"printWidth": 100,
"proseWrap": "never"
},
"husky": {
"hooks": {
"pre-commit": "yarn run precommit-msg && lint-staged"
}
},
"lint-staged": {
"**/**.{js,json,pcss,vue,css,scss}": [
"prettier --write"
]
}

作为略有代码洁癖的我,非常喜欢利用 onchangeprettier 所配置的命令工具:watcher,每当写出代码,便能自动监听变化,将其美化,再也不用手动调整;极大提升了编写效率。为了方便,也有将其封装于 Arya Jarvis :监听并美化指定路径下的代码。如果你喜欢,也能轻松运用。

根据项目情况,自行决定是否引入 commitlint 来督促项目成员有专业化的 commit message 提交。推荐使用gitmojiAn emoji guide for your commit messages,执行git commit 使用 emoji 可以打标签,使得此次 commit 的主要工作得以凸现,也能够使得其在整个提交历史中易于区分与查找。

项目规范

对于各种方法、变量、文件等命名,这无疑是编程最需注重要素之一!

命名规范

  • 语义化:保证命名高度具有可读性,力争做到:见名知义
  • 参数、公有方法名:统一小驼峰(camelCased);
  • CSS 命名:统一短横线(kebab-case),更推荐使用以提升效率;
  • 文件名,文件夹短横线小驼峰都行,统一目录下,请务必保持统一;
  • 类名或公开对象:统一大驼峰(CamelCased);
  • 私有字段或方法:统一加 _ 前缀(_camelCasing);
  • 全局变量:统一加上 g 前缀;Eg:gCoreVersion;
  • 布尔类型值/方法:统一以 iscanhas 打头(同时优先遵循上一条);
  • 事件、方法回调:分别以 onhandle 打头;
  • 常量:统一采用“全大写 + 下划线的方法命名”,Eg: EVENT_LIMITATION;
  • 对象、数组字、符串、数字:建议分别以 ObjArr, Str, Num 结尾,针对容易混淆的命名;
  • 尽量避免使用缩写,除非是大众流行(application => app ✅ group => grp ❌);

所有命名,除非是 for/forEach 内的 key(/item),其他一律要使其该有的语义

代码规范

JavaScript

  • 启用 eslint & JavaScript Standard Style
  • 保证健壮性、可读性、可扩展性、可维护性;
  • 尽可能拆分单一任务,于一个方法之中,使得代码更清晰,更易于复用;
  • 推荐参考 clean-code-javascript,争取写出更干净优雅的代码;

HTML

推荐参考编写一致、灵活和可持续的 HTML 和 CSS 代码的规范;如果想了解更多,可以阅读一直在于维护的:与时俱进版前端资源教程。除此之外,还需要额外补充一些相关要义。

请保证标签语义化,用适当的标签,做相关的事儿;见过有些开发者,喜欢使用 Div 添加 click 事件,辅之以 window.open 来实现链接跳转;这实在很没必要;而且用户也不是很方便使用。另外,设计好 Dom 层级,避免不需要的多层件套;比如,可以基于伪元素 before、after 来实现一些效果,而不用额外增加一些标签。

CSS

CSS:除了尽量使用类(最大限度上不要使用内联样式),准确而优雅的命名之外,请善用预处理工具,对各种 colorsizez-index 等常用的属性,统一定义变量,方便编写,更利于后期维护;同时,还有常用方法,如居中、去浮动、阴影特效等操作统一封装(mixin),提升编写、维护效率,也能缩减源码量;对于 CSS 预处理器,推荐使用 Less 或者 Stylus,而 Sass 会依赖 node-sass,而 node-sass 需要借助 Python 和 C++ 才能编译;跟环境耦合太重,很多时候,会出问题,但通过 npm rebuild node-sass命令,并不是所有时候都能解决问题。

性能检查

每个项目有所区别,请阅读 Front-End Performance ChecklistFront-End Checklist 所给出的建议,确保项目是采取更优的用法。

构建尺寸

如果基于 webpackrollup 来构建应用,请确保每个依赖是合理的,并且所构建出的内容,都是必要的,从而保证包是最轻量的; 可以使用的工具有:webpack-bundle-analyzerrollup-plugin-analyzer 等。

分支命名规范

master 分支

  • master 为主分支,也是用于部署生产环境的分支,确保 master 分支稳定性;
  • master 分支一般由 develop 以及 hotfix 分支合并,任何时间都不能直接修改代码;

develop 分支

  • develop 为开发分支,始终保持最新完成以及 bug修复后的代码;
  • 一般开发的新功能时,feature 分支都是基于 develop 分支下创建的;

feature 分支

  • 开发新功能时,以 develop 为基础创建 feature 分支
  • 分支命名: feature/ 开头的为特性分支, 命名规则: feature/user-modulefeature/cart-module

release 分支

  • release 为预上线分支,发布提测阶段,会 release 分支代码为基准提测

hotfix 分支

  • 分支命名: hotfix/ 开头的为修复分支,它的命名规则与 feature 分支类似;
  • 线上出现紧急问题时,需要及时修复,以 master 分支为基线,创建 hotfix 分支,修复完成后,需要合并到 master 分支和 develop 分支;

对外文档

文档是开源项目的门面,须高度重视;除了认真 CR 内容外,仍有很多其他部分需要注意 ⚠️ ;因此这部分启用 Check List 来说明,以供项目可以一一核查:

  • 是否编写良好 README.md尤其开源项目
  • 专业化排版;如“中英文间留空格“等(prettier *.md尤其开源项目
  • 是否有引入其他方有可能侵权的资源,如视频、图片等;尤其开源项目
  • 是否完善上线及发布日志尤其开源项目

搜索引擎优化清单

  • 安装Google Analytics(分析)
  • 设置 Google Search Console
  • 在 Google 的Search Console中检查抓取错误,重复内容错误,标题丢失和其他技术错误
  • 抽查重定向问题(特别是 302 错误,应该为 301s)Browseo.net
  • 寻找断开的链接,错误和爬行问题 Seo Spider
  • 尝试将主要关键字纳入您的页面网址网址最佳做法
  • 将关键字添加到标题标签。您的标题标签引人注目吗?标题标签预览工具
  • 将关键字添加到您的 H1 标签。确保仅使用一个 H1 标签,并确保它在文档中显示在 H2,H3 等之前。
  • 向页面添加可抓取的文本
  • 是否有配置 title、 description(含社交系)meta;
  • 针对图片指定对应的 altSEO);
  • 是否配置配置 favicon、语言等;
  • 使用对 SEO 友好的文本链接到您网站上的其他页面。内部链接的最佳做法
  • 确保您没有重复的内容(非 www 到 www 重定向)
  • 检查您网站的速度并保持快速!Google Page Speed工具
  • 确保您的网站适合移动设备。Google Mobile Friendly测试工具
  • 创建 XML 网站地图,并将其提交到 Google Search Console
  • 创建 robots.txt 文件并将其提交到 Google Search Console Google Robots.txt
  • 在尽可能多的社交网站上声明您的品牌名称。Namechk
  • 使用 SEO 审核工具仔细检查所有内容。Seo Checklist Analysis

可使用工具:Checklist Tools Website

完备测试

编写测试用例,配置对应 CI,只有通过 CR & CI 的 PR,才给予合并,从而保证项目成员每次拉取下来的代码,是可以正常工作(纯文档项目除外);无论使用 Github 还是 Gitlab 管理项目,都有相关工具可以运用,方便快捷。

于 2020 年 04 月,深圳.福田。

原文首发于个人最新博客:静轩之别苑 — 前端项目开发规范意见

您可能感兴趣的文章


静晴轩 ~ 晚晴幽草轩
个人微信公众号晚晴幽草轩;名字取自:“天意怜幽草,人间重晚晴”。
专注互联网开发(Web 大前端、快应用、小程序),以及分享优质网站、AI 应用、效率工具、心得感悟等内容。

文章目录
  1. 1. 各项配置
  2. 2. 项目规范
    1. 2.1. 命名规范
  3. 3. 代码规范
    1. 3.1. JavaScript
    2. 3.2. HTML
    3. 3.3. CSS
  4. 4. 性能检查
    1. 4.1. 构建尺寸
  5. 5. 分支命名规范
    1. 5.1. master 分支
    2. 5.2. develop 分支
    3. 5.3. feature 分支
    4. 5.4. release 分支
    5. 5.5. hotfix 分支
  6. 6. 对外文档
    1. 6.1. 搜索引擎优化清单
  7. 7. 完备测试
    1. 7.1. 您可能感兴趣的文章