B轮融资|代码注释的艺术，优秀代码真的不需要注释吗？( 三 ) 芯片|创投圈

好代码的最佳僚机
You might think the purpose of commenting is to 'explain what the code does' but that is just a small part of it.The purpose of commenting is to help the reader know as much as the writer did. 译：你可能以为注释的目的是“解释代码做了什么” ，但这只是其中很小一部分，注释的目的是尽量帮助读者了解得和作者一样多 -- Dustin Boswell《The Art of Readable Code》
如同John Ousterhout教授一样， The Art of Readable Code 的作者Dustin Boswell ，也是一个坚定的注释支持者。与Robert C.Martin类似， Dustin Boswell同样认为我们不应该为那些从代码本身就能快速推断的事实写注释，并且他也反对拐杖式注释，注释不能美化代码。但Dustin Boswell认为注释的目的不仅解释了代码在做什么，甚至这只是一小部分，注释最重要的目的是帮助读者了解得和作者一样多。编写注释时，我们需要站在读者的角度，去想想他们知道什么，这是注释的核心。这里有非常多的空间是代码很难阐述或无法阐述的，配上注释的代码并非就是糟糕的代码，相反有些时候，注释还是好代码最棒的僚机。
更精准表述
There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton 译：计算机科学中只有两个难题：缓存失效和命名
Martin Fowler在他的 TwoHardThings 文章中引用了Phil Karlton的一段话，命名一直都是一件非常难的事情，因为我们需要将所有含义浓缩到几个单词中表达。很早之前学Java ，接触到很长的类名是ClassPathXmlApplicationContext 。可能有人认为只要能将含义准确地表达出来，名字长一些无所谓。那如果我们需要有一段处理有关“一带一路”的内容，那我们的代码可能是这样的
public class TheSilkRoadEconomicBeltAndThe21stCenturyMaritimeSilkRoad { 他非常准确的表达了含义，但很明显这不是我们期望的代码。但如果我们辅以简单的注释，代码会非常清晰，说明了简称，也说明了全意，表述更精准。
/** * 一带一路 * 丝绸之路经济带和21世纪海上丝绸之路 */public class OneBeltOneRoad { 代码层次切割
函数抽取是我们经常使用且成本最低的重构方法之一，但并非银弹。函数并非抽得越细越好，如同分布式系统中，并非无限的堆机器让每台机器处理的数据越少，整体就会越快。过深的嵌套封装，会加大我们的代码阅读成本，有时我们只需要有一定的层次与结构帮助我们理解就够了，盲目的抽取封装是无意义的。
/** * 客户列表查询 */public List queryCustomerList(){ // 查询参数准备 UserInfo userInfo = context.getLoginContext().getUserInfo(); if(userInfo == null || StringUtils.isBlank(userInfo.getUserId())){ return Collections.emptyList();LoginDTO loginDTO = userInfoConvertor.convertUserInfo2LoginDTO(userInfo); // 查询客户信息 ListCustomerSearchVOcustomerSearchList = customerRemoteQueryService.query(loginDTO); IterableCustomerSearchVOit = customerSearchList.iterator(); // 排除不合规客户 while(it.hasNext()){ CustomerSearchVO customerSearchVO = it.next(); if(isInBlackList(customerSearchVO) || isLowQuality(customerSearchVO)){ it.remove();// 补充客户其他属性信息 batchFillCustomerPositionInfo(customerSearchList); batchFillCustomerAddressInfo(customerSearchList); 其实细看每一处代码，都很容易让人理解。但如果是一版没有注释的代码，可能我们会有点头疼。缺少结构缺少分层，是让我们大脑第一感观觉得它很复杂，需要一次性消化多个内容。通过注释将代码层次进行切割，是一次抽象层次的划分。同时也不建议大家不断去抽象私有方法，这样代码会变得非常割裂，并且上下文的背景逻辑、参数的传递等等，都会带来额外的麻烦。