1.行为准则
2.代码评审2.1.代码评审是一种给予和接受反馈的专门的形式2.1.1.大多数团队会在合并代码的修改之前进行代码评审2.1.2.评审不是一个证明你有多聪明的机会,也不是一个橡皮图章式的官僚主义障碍2.2.高质量的代码评审文化有助于所有具有不同经验水平的工程师的成长,并促进他们对代码库的共同理解2.3.糟糕的代码评审文化会抑制创新,减慢开发速度,并且导致滋生怨恨情绪2.3.1.执行不力的代码评审会成为一种有害的阻碍2.3.2.轻率的反馈不提供任何价值,还会拖慢开发人员的速度2.3.3.缓慢的周转时间会使代码的变化停滞不前2.3.4.如果没有正确的评审文化,开发人员可能会陷入反复拉锯扯皮的分歧中,这可能会毁掉一个团队3.为什么需要评审代码3.1.评审可以捕捉bug并保持代码整洁3.1.1.代码评审的价值不仅仅是让人来代替自动测试和代码质量检查工具3.2.优秀的代码评审可以作为一个教学工具,传播认识,记录实现的决策,并提供代码的更改记录以确保安全性与合规性3.2.1.你可以从别人评审你的代码给予的反馈中学习3.2.2.评审者会指出那些你可能不知道的有用的类库和编码实践3.3.代码评审也是了解你的团队的编码风格的一种简单方法3.4.评审整个代码库的变更可以确保不止一个人熟悉生产环境中代码的每一行,对代码库的共同理解有助于团队更有凝聚力地扩展代码3.4.1.让别人知道你在改什么,意味着一旦出现了问题,你不是团队中唯一可以仰仗的人3.5.被记录下来的评审意见也是一种文档3.5.1.解释了为什么事情会这样做3.5.2.需要以某种特定方式编写代码的原因并不总是显而易见的3.5.3.可以作为实现决策的档案3.5.4.有旧的代码评审作为参考,可以为开发人员提供一份书面的历史记录3.6.安全性和合规性政策通常规定了代码评审作为一项防范措施来防止任何一名开发人员恶意修改代码库4.当你的代码被评审时4.1.一个精心准备的评审请求可以使开发人员很容易理解你在做什么并提供有建设性的反馈4.1.1.保持单个代码的小幅改动,将特性和重构工作分到不同的评审中,并写出描述性的提交信息,务必将注释和测试包括在内4.2.用评审草案降低风险4.2.1.代码修改的草案是一种思考和提出相应修改的很棒的方式,这种方式不需要投入那么多时间来编写测试、打磨代码和添加文档4.3.提交评审请勿触发测试4.3.1.在本地调试某项失败的测试比在CI环境中更容易一些4.3.2.不能在远程计算机上附加调试器或轻松地获取调试信息4.4.预排大体量的代码修改4.4.1.预排会议4.4.1.1.walk-through4.4.1.2.一种面对面的会议,开发人员在会上共享他们的屏幕,并引导队友了解正在进行的修改内容4.4.1.3.是启发想法和让你的团队适应代码修改的好方法4.5.评审意见是针对代码的,而不是针对你个人的4.5.1.甚至都不算是你的代码,将来整个团队会拥有这些代码4.5.2.得到很多评论是一种完全正常的现象,尤其当你是团队中经验不足的开发者之一时4.6.保持同理心,但不要容忍粗鲁4.7.不要羞于要求别人评审你的代码4.7.1.让代码评审一直悬而未决是不体谅他人的做法5.评审别人的代码时5.1.分流评审请求5.1.1.当你收到评审请求的通知时,你作为评审者的工作就开始了5.1.2.大多数的修改是不那么紧急的5.1.2.1.如果紧急度不明确,请询问提交者5.1.3.你不需要评审每一项代码修改,要专注于那些你可以从中学习的修改和你熟悉的代码5.2.给评审预留时间5.2.1.代码评审类似于运维工作,其规模和频率在某种程度上无法预知5.2.2.大型的代码评审可能需要进行额外的计划5.3.理解修改的意图5.3.1.不要一上来就以提交评论的方式开始你的评审工作,首先要阅读并提出问题5.4.提供全面的反馈5.4.1.需要对代码修改的正确性、可实施性、可维护性、可读性和安全性提供反馈5.4.2.指出那些违反代码风格手册、难以阅读或令人困惑的代码5.4.3.阅读测试用例并寻找bug以验证代码的正确性5.4.4.寻找OWASP十大违规行为5.4.4.1.SQL注入攻击、敏感数据泄露和跨站脚本攻击的漏洞5.5.要承认优点5.5.1.代码评审不一定全都是负面的评论5.6.区分问题、建议和挑剔5.6.1.并非所有的评审意见都有相同的重要性5.6.2.重大问题需要比中性的建议和肤浅的挑剔投入更多的关注5.6.3.在反馈前加上“可选”(optional)、“接受或不接受”(take it or leave it)或“非必须”(nonblocking)的字样5.7.不要只做橡皮图章5.7.1.可能会迫于压力,在没有真正看清楚的情况下就批准了某项评审5.7.2.要抵制那种用草率批准的方式快速给评审盖上橡皮图章的诱惑,橡皮图章式的评审是有害的5.7.3.期望一次性就能充分评审一项巨大的代码改动是不合理的5.8.不要只局限于使用网页版的评审工具5.8.1.代码评审通常在一个专门的UI中处理5.8.2.代码评审本身也只是代码而已5.9.不要忘记评审测试代码5.9.1.评审者经常会忽略测试代码,特别是当变更比较大的时候5.9.2.测试代码应该像代码的其他部分一样被评审5.9.3.一定要检查测试代码的可维护性和清洁度5.10.⑩推动决断5.10.1.不要成为促成“夭折”的原因,要帮助提交者评审以迅速批准他们的代码5.10.2.坚持质量,但不要成为不可逾越的障碍5.10.3.尊重正在进行的修改的范围5.10.4.如果对代码修改有重大分歧,而你和作者又不能解决分歧的话,请主动提出把这个问题移交给其他专家,他们可以帮助解决相关分歧