前端项目开发规范意见

前端开发 Feb 19, 2020

出于整个团队代码可读性、可维护性考量，有必要约定一套基本规范（包括代码命名、基础设施、提交日志、对外文档、测试等方面），供各团队都能参考，从而提升项目可持续性发展，也便于成员之间，能很好提升代码 CoverReview 效率。

项目配置

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

"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"
  ]
}

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

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

这里有必要说明下，代码提交注意事项：应该对于每个新增功能，或者每个修改的 bug，都y与之对应一个 commit；从而使得其他人，能够清晰的知道完成某个功能（修复某个问题），对应的实现代码是什么，便于了解、Code Review 等等；也对后续维护、回顾，能够起到很大参考作用。同时，也避免设备偶然出现的问题，导致代码丢失带来的返工风险。

项目规范

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

命名规范

  • 语义化：保证命名高度具有可读性，力争做到：见名知义；
  • 参数、公有方法名：统一小驼峰（camelCased）；
  • CSS 命名：统一短横线（kebab-case），更推荐使用类以提升效率；
  • 文件名，文件夹：短横线，小驼峰都行，统一目录下，请务必保持统一；
  • 类名或公开对象：统一大驼峰（CamelCased）；
  • 私有字段或方法：统一加 _ 前缀（_camelCasing）；
  • 全局变量：统一加上 g 前缀；Eg：gCoreVersion；
  • 布尔类型值/方法：统一以 is、can、 has 打头（同时优先遵循上一条）；
  • 事件、方法回调：分别以 on、handle 打头；
  • 常量：统一采用“全大写 + 下划线的方法命名”，Eg: EVENT_LIMITATION；
  • 对象、数组字、符串、数字：建议分别以 Obj，Arr, 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：除了尽量使用类（最大限度上不要使用内联样式），准确而优雅的命名之外，请善用预处理工具，对各种 color、size、z-index 等常用的属性，统一定义变量，方便编写，更利于后期维护；同时，还有常用方法，如居中、去浮动、阴影特效等操作统一封装（mixin），提升编写、维护效率，也能缩减源码量；对于 CSS 预处理器，推荐使用 Less 或者 Stylus，而 Sass 会依赖 node-sass，而 node-sass 需要借助 python 和 c++ 才能编译；跟环境耦合太重，很多时候，会出问题，但通过 npm rebuild node-sass命令，并不是所有时候都能解决问题。

性能检查

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

构建尺寸

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

分支命名规范

master 分支

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

develop 分支

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

feature 分支

  • 开发新功能时，以 develop 为基础创建 feature 分支
  • 分支命名: feature/ 开头的为特性分支， 命名规则: feature/user-module、 feature/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；
  • 针对图片指定对应的 alt（SEO）；
  • 是否配置配置 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 管理项目，都有相关工具可以运用，方便快捷。

您可能感兴趣的文章

Tags

nicejade

Recommended for you

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.