Git
git的用户名为自己名字的小写全拼,邮箱为公司邮箱,方便追溯提交者。命令行操作示例:
git config --global user.name myname
git config --global user.email myemail@example.com
git commit
的log原则:
- 必须说明提交的意义,不能是简单无意义的文字
- bug fix应写上是解决哪个bug,可复制“bug系统”上的ID和标题
- 做需求应写是哪个需求;分批提交应写上完成了什么具体内容
- 每做一个任务(解bug、重构或做需求)就commit一次,不要一次commit里做了多个任务。方便做code review和代码回滚。
平时拉取代码,不准用git pull
,要用git pull --rebase
。杜绝merge信息,方便查找历史。下图是反例:
分支管理请参考《Git分支管理规范》。
代码规范
各技术组自己决定代码风格规范,可参考google、apple、facebook、alibaba、airbnb、microsoft任一家的。并可找些自动格式化和检查工具作为辅助。例如移动开发可参考《移动开发代码规范与格式化工具》。
代码的文件组织(目录结构)规范应在README.md
中说明。
其它一些准则:
- 类名、函数名、变量名仔细斟酌,要能代表意义,不要怕长。由此就尽量不要对这些东西写中文注释了,一是翻译一遍浪费时间,二是无意义地增加信息量减慢了看代码速度。
- 遗留工作要写
TODO
。待优化的地方要写FIXME
。 - 同一功能的代码要做好内聚,不要学新手是把同一类型的代码放一起。
- 没有用的代码都删掉,不要变成注释留在原地。特别记得要删除开发过程的调试代码。
- 干掉所有warning!
文档规范
新项目必须画系统架构图、网络拓扑图等宏观设计的图,便于新同学或测试组同学理解。无论在哪里写的,最后都应该复制一份一同提交到代码仓库,例如放在代码的docs
目录。
好的代码应该只需要描述宏观架构和设计思路就能让新人上手,细节的设计是通过代码注释和增强代码可读性来体现的。快速的迭代节奏不会有时间写详细设计,且变化太快也来不及更新文档。
README.md
(代码说明)还可以包括这些内容:
- 迭代历史:可包括开发人员和代码历史。
- TODO list
- 工具使用说明
- 第三方依赖的参考文档URL
- 特殊的设计、约定
- 项目关联的文档地址,例如需求文档、服务器接口文档等
- 各种系统的一些公用的低机密性账号密码,例如测试账号
前后端合作都以API为媒介,所以API文档是必须的。怎么设计API规范,可参考《Web API规范设计指引》。
Review制度
哪些情况应该主动请求review:
- 有可能破坏了整体的设计风格、规范
- 代码所属的功能非常重要,出错的话会造成公司业务重大损失
- 改动范围很大,会改到另外2个或以上同事写的较多代码
Review关注点:https://blog.csdn.net/hursing/article/details/125424834
本节参考
《Git分支管理规范》
《移动开发代码规范与格式化工具》
《Web API规范设计指引》
《Code Review关注点》
本系列文章的目录:https://hursing.blog.csdn.net/article/details/88025790