抱怨项目里的坑是个再常见不过的事情了：

• kissy 版本过低 (<1.3.x)
• 项目没有 README
• 代码很糟糕：没有注释？耦合度高？线上小 bug 不断？whatever.
• ...

如此种种，然后说说我碰到过最糟的情况吧：

• 新接手的业务，没有交接的过程，我只能从 git commit 里依稀分辨出谁曾经维护过...
• 项目里混用了 stylus 和 less, 并且 Gruntfile.js 里没有任何跟编译 less 和 stylus 相关的配置，现在想想也觉得异常吊诡
• 不出意外，README.md 的内容字节数为 0

这大概也没有什么......吧，不过另一个重点是，在我接手半年之后，这个项目除了多了一份还算 OK 的 README 以外，一切照旧！大概会让你很失望，这明明应该是个满是鸡汤味的励志故事才对啊。

其实，我内心曾经呐喊过很多次:「我要填了这万恶的坑」。而最终却只是多了那一份字节长度大概在 200 左右的 readme, 所以，我为什么没有填起这些坑？

为什么我不愿意填坑

需要承担风险

在对业务不够熟悉的情况下，重构是有风险的，所以我需要申请测试资源，测试同学又不傻。

没有时间

无论是从业务方，还是 TL 的角度，大概都不希望把时间放在重构上，除非说，这个项目的代码再不重构就要挂了。

业务需求太少

上面提到的那个业务，半年来做过一次不大不小的需求，然后就是最近的 https 升级，填完坑也不见得能对我或者对业务产生什么价值。

归根结底一句话「投入产出比太低」，所以多数情况下没有人愿意去填别人的坑。既然如此，那我们进入本文的正题少挖坑。自己负责的业务，争取不留或者少留坑更加有意义，同时只要愿意更容易实现。接下来就结合自己的一些实践，从 readme, git, code, lint... 等方面提出一些建议，欢迎补充纠正:)

如何做到不挖坑

一份可读的 README

任何一个项目都应该起于一份 README.md, 接到一个新的需求：创建 git 分支 -> 编辑 README -> 编码 -> 测试 -> 发布，如此多好。

同时一份可读的 README 应该至少包括一下内容：

# 某某业务## 介绍：- kissy 版本：kissy 1.4.x
- 打包工具：xcake
- 业务：xx 业务，可以罗列下线上地址
- 开发者：@xx## 升级日志：### v1.0.0https 升级###  v0.1.0增加 xx 需求## 目录：罗列大体的项目目录结构（在根目录下运行 tree -L n 即可生成目录结构图，n 指层级深度）## 其他：- 注意的地方，坑？
- and whatever

另外，如果在项目里使用了新的技术，如 Angular, React... 那应该有更详细的沉淀文档。

及时剔除无用代码

从来只见业务在不断新增需求，却不见将老的需求/页面下掉，但凡是有那么一点点 PV, 美其名曰「为用户着想」，时间长了，任谁也想不起那一坨页面是什么玩意，直到有一天...https 改造了！

于此对应，我们多数时候只会新增代码，而不愿意删除代码，即时这个需求已经下掉了，或许心里想的是「哪天也许会再次使用这个功能呢」。久而久之，一个本身并不复杂的业务代码越积越多，冗余度越来越高。And then, 骚年，这个业务你来接手吧。

上面两种情况，其实原因只有一个「删除是有风险的，而新增是安全的」，多数时候，我们更喜欢安稳点的方案。

从明天起，做一个熟悉代码并敢删除代码的人。

良好的 git 操作习惯

1) 正确管理版本号

很多人没有理解 x.y.z 版本管理的理念，而只是一味的在某一位上不断增加，或者说大多数人在接到一个需求时，根本不会考虑应该是升级 major, minor, 或者 patch 的版本号，这是万万不对的。

x.y.z 是一套语义化版本控制规范(SemVer), 各版本号递增规则如下：

主版本号：当你做了不兼容的API 修改， 次版本号：当你做了向下兼容的功能性新增， 修订号：当你做了向下兼容的问题修正。

具体的文档可以阅读 语义化版本2.0.0。

2) 有意义的 commit 信息

• git commit -am 'debug'
• git commit -am 'fixed bug'
• git commit -am 'modify'

诸如此类毫无意义的 commit 信息，在 gitlab 的 timeline 上随处肆虐。对于 commit 遵守以下两个原则即可：

• 每个提交应当只包含一个简单的逻辑改动，不要在一个提交里包含多个逻辑改动。比如，如果一个补丁修复了一个 Bug，又优化了一个特性的性能，就将其拆分。
• 不要将一个逻辑改动拆分提交。例如一个功能的实现及其对应的测试应当一并提交。

更多请戳 git-style-guide

3) 为 tag 添加注释

常用的发布姿势：

git tag publish/1.0.0
git push origin publish/1.0.0

更好的发布姿势：

// 为 tag 添加信息
git tag -a publish/1.0.0 -m 'https 升级'
git push origin publish/1.0.0

如下面左右两幅图片对比，为 tag 做注释，等于自动生成升级日志，一目了然，何乐而不为。

统一自己的代码规范

我曾经问师兄：「为什么我们没有一份代码规范的文档？」，师兄的回答是：「规范是用来打破的」。

规范是用来打破的，虽说没有太好的说辞去反驳，但事实上我是不认同这句话的，我倒是觉得规范一来能在一定程度上保证代码的质量，二来对于多数人可以提供一个参考。那这时候我又要推荐 Airbnb 整理的 Airbnb JavaScript Style Guide() { 以及 对应的 es6 style, 认真阅读一遍，一定会有收获。

当然，对于喜欢打破规范的同学来说，打破规范自然没有任何问题，只需做到一点：坚持一套自己统一的风格:)

用 editorconfig 统一编码规范

同一个项目，可能会有 N 个开发者，tab or space? 2个空格 or 4个空格？gbk or utf-8? 不要吵，让 editorconfig 来。

通过项目根目录下的 .editorconfig 来配置这些规则，配合编辑器的 editorconfig 插件，使用之后，自定义的规则会覆盖掉编辑器设置，保持整个项目的一致性。

例如 xcake 默认生成的：

root = true[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true[*.md]
trim_trailing_whitespace = false

用 eslint 保持代码风格一致性

同一个项目，可能会有 N 个开发者，单引号 or 双引号？要不要分号？== or ===? 试试eslint 吧，比 jslint 更加容易自定义规则。

话说，还没来得及细细对比 eslint 和 jslint, 又来了一个 JSCS, 有时间可以了解下。

如果愿意，以上皆可定义为规范，很多时候我也不见得会全部遵循，但挑中自己认同的，在项目中实践一二也是极好的。

以上。

本文转载自：http://sobear.me/2015/04/talk-about-keng.html

作者：大果