作者|原神剑接上一篇《??如何编写简洁代码？（上）??》代码中不说实话的直接后果就是大家被误导了，然后就做了错事，在不知情的情况下犯了错误，把错误弄得更深更深了浪费宝贵的时间。不过你别说，写代码的人不是故意的，他绝对不能上网。袁帅秉承内训师作为知识沉淀者和文化传播者的原则，借教育代码内部座谈会的机会，组织了一个部门，美其名曰：CleanCode交流会。你说的是实话吗？周五是放松的一天，距离年会已经快整整一周了。袁帅也借此机会把开发在线学习系统的团队中的几位小伙伴叫了过来，和代码聊了聊。看似无意的安排，其实他早有准备。仿装修的会议室里，袁帅开门见山：“最近我在和一个北美BP洽谈，要给他们大客户团队的核心成员加强敏捷工程实践，现在很多部门都有一套敏捷工程内部练习课程。不过有意思的是，这个BP在和我在线交流的时候，从来没有一步到位，总是发微信给我再解释一遍，不知道我有没有看愚蠢的，或者她认为我精神错乱。”袁帅这话一开口，众人都有些意外，他被逗乐了，好奇地看了他一眼，“我没说清楚，我再告诉你。”青扬一副若无其事的样子。开会说清楚了，她又要给我解释一遍，而且每次微信上的留言都比她开会时说的更清楚、更具体。所以，我渐渐习惯了开会不理她，给的信息，就看她的微信了，有时候她在后续的会议上更新了之前的消息内容，忘记给我留言了。”袁帅一脸无辜。“所以，你还是关注了微信留下的信息，却误会了真正的意思！”青扬急切的应道。“哎，你别说了，我最近没跟活人打过交道，老是遇到这种麻烦。”袁帅试探着故作惊讶。“评论，最近看到了一些代码评论。不看注释，花点时间思考代码，也能搞清楚代码是干什么的，但有时候想走捷径。看了一眼评论，发现评论不对。我去兜兜转转，被谎言牵着鼻子走，真的很烦人！”欢欢开玩笑地补充道。我总是习惯于添加一些点缀。本来初衷是好的，想解释的更清楚，但是点缀只是补充信息。有时候原来的信息变了，点缀的却没有跟进更新，不仅起不到装饰的作用，反而会误导别人，耽误事情！”袁帅同情地答道。”说白了，我还是没搞清楚代码是干什么的，然后觉得需要通过注释来解释一下，如果后面改了代码，大概率注释不会修改”正义永远充满正义。“用中文注释可能更容易阅读，因为代码不容易用中文名字。”程晓娜用理解的语气弱弱的补充了一句。袁帅顿时陷入了沉思，脑海中出现了两个画面：他辅导过的一些程序员，由于英语水平很差，很难将中文翻译成合适的英文，这在一定程度上限制了他们，甚至还要借助翻译。工具。有一次，为了给一个方法命名，他和三个有10年以上工作经验的技术负责人讨论了10分钟左右，终于搞??定了，但大家都很高兴。“为什么要写注释？代码不是自解释的吗？只有当代码无法解释自己时，才可以使用注释！”正义越来越正义。“但有时方法太长，要做的事情太多，不建议每段相关代码都用注释来解释你在做什么，对吧？”程扬适时地抛出了一个问题。“说话很便宜，给我看代码！”袁帅展示了准备好的代码：“请在2分钟内仔细阅读这几段代码，并将您看到的问题和建议的改进措施发到我们的讨论群里哈。”5分钟后，袁帅总结了大家的答案：例1：类上的注释完全没有必要，因为VCS工具可以记录的很好。例1：构造方法上的注解是多余的，构造函数本身可以表示构造的对象，参数也可以表示传入的东西。示例2：方法的注释确实起到了解释的作用，但是让方法不言自明更香：将名称更改为listByStatus后，去掉注释。紧接着，袁帅又抛出了一个复杂的例子：大家花了3分钟才找出问题所在：例子3：方法太长，中段注释说明了要做什么。可以抽取方法，然后将注释转换成方法名来表达意图。示例3：printReceipt方法打印日期，客户忠诚度评论过期，实际上代码被注释掉了。例3：printReceipt方法中的税率是15%，但实际是10%，用来误导读者。“评论也不是没用，毕竟谁说的——‘存在就是合理的’。评论存在了这么多年，我们在很多地方都看到过。”袁帅恢复了版主身份。“是啊，《OpenAPIDocumentation》里满是API注释，得好好写。””“最近有几段代码实在是难言之隐，不得不通过注释来解释一下。”“嗯，我只是在“正版信息”上看到了一些注释，白纸黑字的注释和声明是少不了的。""魔术代码可以注释，比如复杂的邮件正则表达式：/^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;”袁帅对最后的加法有点兴趣，趁机发问：“除了评论，魔法还有没有更好的办法？代码？？""引入"解释变量"，如：emailMatcher。“这次青阳当场反应非常快。”您如何看待评论“TODO|FIXME”？”清阳立即问道。不推荐，虽然可以帮助我们在本地记录一些to-dolist，但是尽量及时完成这些任务，清理评论，不要提交生产。”正义的声音笼罩全场。袁帅对青阳和正一竖起大拇指，简单总结道：“有些场景需要注释一下。当我们要添加注解的时候，我们应该先想好。代码是不言自明的吗？”他在收拾电脑的时候，脑海中浮现出鲍勃大叔关于注释的一句话：“注释和《辛德勒的名单》是不一样的。它们不是“纯粹的善”。事实上，注解充其量是一种必要的邪恶。”——RobertC.MartinMartinFowler的博客上有一句话：“计算机科学中只有两件难事：缓存失效和命名事物。”这句话不是老马自己说的，老马很赞同，而袁帅也很赞同，越看越服气，距离上次CleanCode交流会刚好一个星期，今天天气特别晴朗，小饭馆里炒了两道菜。当两人来到餐厅刚坐下，袁帅的手机微信语音就响了，是隔壁团队的TL史彪，想找他聊聊大家上次TDDworkshop后的落地情况和疑惑。出去递了菜单示意袁帅要点东西，袁帅只是说了句“青菜”就继续和石彪聊着天。他，一株清蒸桂花我们鱼，外加两份本地鸡汤和米饭。十分钟后，“青菜”出来了，袁帅咬了两口，感觉不对：“咦，我点的是青菜，怎么点了生菜？”“哥，我尽力了，没找到‘青菜’，就点了这个。”青阳一脸无辜。“哦，我们有一种蔬菜叫‘上海青’，我们平时都叫它青菜。”袁帅立刻意识到，自己现在是在北方，这里的名字可能和他的家乡不一样。“哈哈，我们西安人都把青菜理解为青菜~”青扬说着将菜单递了过去。看到“炒菜子”，袁帅开始在心里想：“不同地区（语境）可能对同一个东西的称呼不同，换个地区，我还是用原来地区的名字，可能会造成混乱，误解。”“在不同的行业，不同的领域，不同的语境，同一个东西可以有不同的名字。你经常跟我说，写代码的时候要特别注意这一点，要用行业的系统，为那个行业开发一个系统。”业务语言有利于统一语言，沟通效率会高很多，而且代码与业务相匹配，更容易理解。”青扬猜到了袁帅的心思，帮他总结了一下。“你的清蒸桂花鱼，你慢慢用吧！”服务员把香喷喷的鱼端上桌。这是袁帅小时候非常喜欢的一道菜。他高兴地拿起筷子，正要夹起鱼尾：“咦，刚才服务员叫它清蒸桂花鱼？”“没错，桂花鱼，清蒸，营养健康，色香味俱全。”青阳反应很快。袁帅拿起菜谱看了一眼，嘀咕着，似懂非懂地点点头：“在我老家，这道菜叫‘清蒸桂鱼’。青扬看了他一眼，摇头叹息，伸手接了过来。把鱼端上来，开开心心的吃起来。这顿饭我吃~”袁帅这回赶紧从给菜品命名的念头中抽身出来。吃过晚饭，袁帅打电话给青阳查看隔壁石飚团队正在做的CodeReview，看到大屏幕上的代码screen:"小豹子，这个FlyLine是指飞行路径吗？石彪小心翼翼的问道。“嗯，就是这个意思！”“《你在IDE里搜索【Route】】我看到小宝熟练地使用快捷键定位到一个Route类：看到这个类，小宝很快在打开的谷歌翻译框里找到了【Route：Route】。”你打开Trello卡片上的【航空术语】，那张卡片上有航空术语的链接，打开页面，输入关键词【航线】进行搜索，见小宝下意识挠头，石飚又提示了一句。石飚指尖操作了10秒后，大屏幕上显示出页面：“小豹子刚来，对这些航空行业术语不熟悉也无可厚非。我们是做航空系统的，所以我们需要说航空术语。”史彪扫了一眼在场的所有小伙伴，继续说道：“那你们是怎么学这些行话的呢？翻译工具是个好帮手，但有时候也不好用。我们的团队一直在维护一套专门的术语，并且上周我刚把它开发成网页版，部署在内网服务器上，我们可以随时在上面搜索术语。”史彪说完，小宝立马和示意配对的小伙伴们在卡片上写下了一个Action：【替换Flight类中引用的Flyline-->Route】。总结如“??域冗余”，“码尾禅”，而“层层错综”是代码沟通表达的偏形式，那么“伪修改”和“布局”就是分心，这些看似语无伦次的假话更容易骗人，写个码本没什么大不了的，努力打磨这五点，时时review代码，时时反省，软件的可理解性至少可以提高90%，已经很高了。
