开源中国

我们不支持 IE 10 及以下版本浏览器

It appears you’re using an unsupported browser

为了获得更好的浏览体验,我们强烈建议您使用较新版本的 Chrome、 Firefox、 Safari 等,或者升级到最新版本的IE浏览器。 如果您使用的是 IE 11 或以上版本,请关闭“兼容性视图”。
JavaScript 项目最佳实践指南 - 技术翻译 - 开源中国社区

JavaScript 项目最佳实践指南 【已翻译100%】

标签: <无>
oschina 推荐于 2个月前 (共 25 段, 翻译完成于 07-14) 评论 1
收藏  
79
推荐标签: 待读

在开发一个新项目时,就像在一个绿色场地上来回翻滚,维护它对其他人来说可能是一个潜在的黑暗而扭曲的恶梦。以下是我们发现、编写和收集的指南列表(我们认为)在 hive 上的大多数 JavaScript 项目都能很好地工作。如果你想分享最佳做法,或者认为应该删除这些指南之一,请随时与我们分享。

  • Git

  • 文档

  • 环境

  • 依赖

  • 测试

  • 结构和命名

  • 编码风格

  • 日志

  • API 设计

  • 协议

Tocy
 翻译得不错哦!

1. Git

1.1 一些 Git 相关的规则

有这样一些规则需要牢记。

  • 开一个独立的 feature 分支写代码

    为什么:

    因为这样就可以在一个专用的分支上把所有的开发工作都做完,而不会动主分支。你就能提交多次推送请求而不致把事情搞乱,不会因为写了潜在的不稳定、未完成的代码而搞坏了 master 分支。了解更多...

  • 分支要同 develop 分支独立出来

    为什么:

    这样你就可以确保 master 分支里面的代码总是可以无误的通过构建, 并且总是可以直接用来做发布 (这一点对于有些项目而言可能有点矫枉过正了)。

  • 永远不要向 develop 或者 master 分支推送,而是要发起 Pull Request。

    为什么:

    这样做会通知团队成员说他们已经完成了一项功能的开发。同时也能很容易就进入同行代码评审的流程,并且能有一个把拟提交功能拿到论坛进行充分讨论的过程。

  • 在推送你开发的功能并发起一次 Pull Request 之前,要更新你的 develop 分支然后做一次代码库重设。

    为什么:

    重设会在所请求的分支( master 或者 develop )中进行代码合并,并将你在本地所做的提交应用到顶层的历史记录之上,而无需再去创建一次合并提交(假设写的代码没冲突)。这样做能维持一个整洁干净的历史记录。了解更多 ...

  • 在进行重设并发起 Pull Request 之前先解决潜在的代码冲突。

  • 在合并之后要删掉本地和远程的 feature 分支。

    为什么:

    已经没用的分支会把你的分支列表搞得乱七八杂。这样做可以确保你只会讲分支合并到 master 或者 develop 中一次。Feature 分支应该只存在于开发工作还在进行的那段时间。

  • 在发起一次 Pull Request 之前,要确保 feature 分支可以成功构建并且可以通过所有的测试(包括代码风格的检查)。

    为什么:

    现在是你要把代码添加到一个稳定的分支上。如果你的 feature 分支测试失败了,就有极高的风险导致目标分支也构建失败。此外你还需要在发起一次 Pull Request 之前进行一下代码风格检查。这样做有助于提高代码可读性,并减少在实际的修改中所进行的格式化修复工作变乱。

  • 使用这个 .gitignore 文件

    为什么:

    这个文件里面已经有了一份列表,列出来那些不应该同你的代码一起被发送到远程代码库的系统文件。此外,它还排除了哪些最常被使用的编辑器的设置目录以及文件,还有最常用的依赖目录。

  • 保护你的 develop 和 master 分支。

    为什么:

    这样做可以让你的准生产分支不受不可预期且不可回退的修改的破坏。从 Github 和 Bitbucket 了解更多。

leoxu
 翻译得不错哦!

1.2 Git 工作流程

大多是由于上述的原因,我们使用带有主动重设功能特性分支开发工作流(Feature-branch-workflow还有 Gitflow (命名并拥有一个 develop 分支)的一些元素。主要的步骤如下:

  • 检出一个新的 feature/bug-fix 分支

    git checkout -b <branchname>
  • 修改代码

    git add
    git commit -a

    为什么:

    git commit -a 会启动一个编辑器,让你能将代码的修改的主题从代码中分离出来。在章节 1.3 中可以了解到更多

  • 与远程进行同步,获取本地错过的那些修改。

    git checkout develop
    git pull

    为什么:

    这样做让你可以在(稍后)进行重设的时候有机会在自己的机器上处理代码冲突,而不是创建出一个包含了冲突的 Pull Request。

  • 通过主动进行重设来从 develop 分支拿到最新的修改更新 feature 分支。

    git checkout <branchname>
    git rebase -i --autosquash develop

    为什么:

    你可以使用 --autosquash 来将所有的提交操作捆成一次提交。没有人会想要在 develop 分支中针对一个功能的开发做多次提交。了解更多...

  • 如果你的代码里并没有冲突,那就跳过这个步骤。如果有冲突,那就先处理掉它们然后再继续进行重设

    git add <file1> <file2> ...
    git rebase --continue
  • 推送你的分支。重设会改变历史记录,所以你得使用 -f 来将修改推送到远程分支。如果另外还有一个人正在你的分支上写代码,就使用负面影响较小的 --force-with-lease 吧。

    git push -f

    为什么:

    当你在进行一次重设的时候,就是在对你的 feature 分支上的历史记录做变更。这样做的结果就是 Git 会拒绝一般的 git 推送,这时候你就需要用到 -f 或者 --force 标识了。了解更多...

  • 发起一次 Pull Request。

  • Pull request 将会被审查人接收,合并到主分支以后关闭。

  • 如果上述的工作都做完了,就可以删除你本地的 feature 分支了。

leoxu
 翻译得不错哦!

1.3 书写良好的 commit 信息

制定并坚持使用的良好的 commit 指导方针,能让 Git 与他人协作更容易。这里有一些经验原则(来源):

  • 将主题行与正文之间用换行符分开

    为什么:

    拥有正文部分可让您对代码审阅者进行有用的解释说明。如果您可以链接到相关联的 Jira ticket(bug 管理系统)、GitHub issue 、Basecamp to-do 等。大多数桌面 Git 客户端在其 GUI 中的主题行和正文之间都有明确的分隔。

  • 将主题行限制为50个字符

  • 对主题行进行大写

  • 不要用时间来作为主题行的结尾

  • 在主题行中使用必要的祈使语气(imperative mood

  • 将正文限制在72个字符以内

  • 正文应该是用来解释是什么,为什么,而不是怎么办

亚林瓜子
 翻译得不错哦!

2. Documentation 文档

  • 使用此模板创建 README.md ,随意添加未覆盖的内容。

  • 对于具有多个存储库的项目,请在各自的 README.md 文件中提供它们的链接。

  • 随着项目的发展,保持 README.md 的更新。

  • 注释你的代码,尽可能使每个主要部分的目标尽可能清晰。

  • 如果在 github 或 stackoverflow 有关于你所使用的代码或方法的公开讨论,请在你的注释中包含对应链接。

  • 不要将注释作为糟糕代码的借口。 保持你的代码干净。

  • 不要使用纯净的代码作为借口,根本不注释。

  • 随着代码的发展,保证注释相关。

Tocy
 翻译得不错哦!

3. 环境

  • 根据项目规定,定义单独的开发、测试和生产环境。

    为什么:

    不同的环境可能需要不同的数据、令牌、API、端口等。您可能需要一种独立的开发模式,可以调用返回可预测数据的虚拟 API ,从而使自动化和手动测试更容易。或者您可能只想在生产环境加入 Google Analytics 等等。阅读了解更多...

  • 从环境变量加载您的特定配置,不要将它们作为常量添加到代码中,请查看此示例

    为什么:

    您配置的令牌、密码和其他有价值的信息,应该正确地与应用程序分开,就像代码可以随时公开一样。

    怎么做:

    使用 .env 文件来存储变量,并将它们添加到 .gitignore 中以便被 git 排除。提交一个 .env.example 作为开发人员的指南。对于生产环境,您仍然应该以标准方式设置环境变量。阅读了解更多

  • 建议您在应用程序启动之前验证环境变量。使用 joi 查看这个简单验证提供的值 示例

    为什么:

      总有一天它会拯救某人的故障排查。

亚林瓜子
 翻译得不错哦!

3.1 开发环境一致性:

  • 在 package.json 中设置 node 版本

    为什么:

    它让别人知道项目工程的 node 版本。 阅读更多...

  • 另外,使用 nvm 并在您的项目根目录中创建一个 .nvmrc 。 不要忘了在文档中提及它

    为什么:

    任何使用 nvm 的人都可以使用 nvm 来切换到合适的 node 版本。 阅读更多...

  • 您还可以使用 preinstall 的脚本来检查 node 和 npm 版本

    为什么:

    某些依赖项可能会在较新版本的 node 中使用失败。

  • 使用 Docker 镜像,只要它不会使事情更复杂

    为什么:

    它可以在整个工作流程中为您提供一致的环境。不需要操心 libs 、依赖或配置。 阅读更多...

  • 使用本地模块安装,而不是使用全局安装的模块

    为什么:

    让你与你的同事分享你的工具,而不是期望在他们的系统上安装它。

亚林瓜子
 翻译得不错哦!

4.依赖项

在使用包之前,请检查它的 GitHub 。 检查问题的数量,每日下载次数和贡献者数量以及上次更新软件包的日期。

  • 如果需要了解依赖项,请在使用之前与团队进行讨论。

  • 跟踪您当前可用的软件包:例如,npm ls --depth = 0。 阅读更多...

  • 查看您的任何包是否已被使用或不相关:depcheck。 阅读更多...

  • 检查下载统计信息以查看依赖项是否被社区大量使用:npm-stat。 阅读更多...

  • 检查依赖项是否具有良好的成熟版本发布频率与大量维护者:例如,npm view async。 阅读更多...

  • 始终确保您的应用程序适用于最新版本的依赖项,而不会被破坏:npm outdated。 阅读更多...

  • 检查软件包是否存在已知安全漏洞,例如 Snyk 。

亚林瓜子
 翻译得不错哦!

4.1 一致性依赖:

  • 在 npm@5 或更高版本上使用 package-lock.json

  • 对于旧版本的 npm,在安装新的依赖关系时使用 --save -save-exact,并在发布之前创建 npm-shrinkwrap.json 。

  • 或者,你可以使用 Yarn ,并确保在 README.md 中提及它。你的 lock 文件和 package.js 在每次依赖关系更新后都应具有同样的版本。

  • 在这里阅读更多:package-locks | npm Documentation

Tocy
 翻译得不错哦!

5. Testing 测试

  • 如果可能,请使用测试模式的环境。

  • 将测试文件放在测试模块旁边,使用 * .test.js 或 * .spec.js 命名约定,如 module_name.spec.js

  • 将其他测试文件放入一个单独的测试文件夹中以避免混淆。

  • 编写可测试代码,避免副作用,提取副作用,编写纯函数

  • 不要写太多的测试来检查类型,而是使用静态类型检查器

  • 在进行任何 pull 请求开发之前,请先在本地运行测试。

  • 记录你的测试,并附上说明。

Tocy
 翻译得不错哦!
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们
评论(1)
Ctrl/CMD+Enter

@leoxu "在推送你开发的功能并发起一次 Pull Request 之前,要更新你的 develop 分支然后做一次代码库重设。" -- 说的是git的rebase吧?普遍不是应该译成『变基』吗?
顶部