注释是恶魔，请不要再写一行注释

如果你找到的代码没有出现上面两种毛病而注释依然存在那你再看看这个注释是否有实际意义是不是这个注释不要也无所谓呢。注释是恶魔这个观点可能你第一次看到你可能很难接受因为写了这么多年的注释你从未想过注释居然是恶魔所以你看到这个观点的时候可能就会本能的找出1000种理由反对绝对不可能实现啊什么的但是这个观点并不是今天才出现相信很多年前就有人提出现在已被越来越多的人认可。我第一次接受到这个观点还是从一个美国客户十几年编程经验的技术大牛那里2011年他让我们不要写注释。他当时主要意思是我们写的中式英语他猜起来太费劲所以他后面又安慰我们说“好的代码是不需要注释的”而我从此就将他后面那半句话奉为至宝。注释是恶魔它将我们的代码变得很难理解。就像本文开篇说的你可以找找你们项目中出现注释的地方要么命名不准确要么方法太长。你可以随机找10处注释看看有几处是恶魔欢迎贴到评论中。举一个以前项目中的例子吧命名不准确的例子/// summary /// 管理员是否可以审核该申请 /// /summary public bool IsAudit { get; set; }在这个例子中其实将is换成can就不需要注释了。写注释让代码更难读。首先如果一个程序员可以随便写注释那么他对命名准确性和方法长度的控制就不会那么在意写代码更随意代码质量比不能写注释的程序员更大几率低下。其次代码注释只是在写代码的时候提供说明如果读代码都依靠注释的话那一个类被另一个类引用来引用去的就根本没法阅读了。所以“写注释是为了让代码更易读”本身就是站不住脚的。不写一行注释根本就做不到这句话可能从你阅读本文开始在心里面重复了无数遍这也是大多数人的心声。其实前面说的写注释让代码更难读的观点很多朋友从内心上是认可的。因为确实没有办法啊有的方法业务逻辑复杂不知不觉方法已上百行有的命名还是中西结合的不写注释自己第二天就读不懂了。所以真是纠结内心承受百般折磨。写到这里突然想起在园子里看到的一个笑话说一个公司的产品每年都在更新换代因为每年新招的程序员都要把程序重新写一遍。“零注释”根本做不到如果你丛刻开始怀疑自己的这个观点那你就可能做得到。如何做到不写一行注释1. 从现在开始强迫自己不要写注释。2. 控制每个方法不超过50行用方法定义来描述方法的实现逻辑。3. 变量命名不要太过随便。本文想要告诉大家的是零注释一点都不难。我们团队大约从2012年开始全面执行零注释后面经历2个产品项目多个外包项目积累的经验越来越多获得的质量效果越来越好零注释越来越深入人心。零注释这个编码规则也是我们团队近些年质量建设非常重要的里程碑之一再此分享给大家。如果能够影响你一点点那都足够了。附2个我们的代码片段虽没有注释大家不妨猜猜这两个方法做什么用的。1. 查询的例子1 public PageResultIssueDto Search(IssueSearchCriteria criteria, PageRequest request) 2 { 3 using (var db base.NewDB()) 4 { 5 return db.Issues 6 .WhereByAssignee(criteria.AssignedUserId) 7 .WhereBySupervisor(criteria.SupervisorUserId) 8 .WhereByCategory(criteria.CategoryId) 9 .WhereBySearchStatus(criteria.Status) 10 .WhereDateRange(criteria) 11 .WhereNotDeleted() 12 .WhereByKeyword(criteria.Keyword) 13 .ToDtos() 14 .OrderByDescending(x x.CreatedTime) 15 .ToPageResult(request.PageIndex, request.PageSize); 16 } 17 }2. 更新的例子1 public void Submit(Guid userId, string content, string text, double lng, double lat, string address) 2 { 3 using (var db base.NewDB()) 4 { 5 var issue new Issue(userId, content, text, lng, lat, address); 6 db.Issues.Add(issue); 7 db.AddIssueLog(IssueLog.CreateOnSubmit(issue.Id, db.Users.GetNickName(userId))); 8 db.SaveChanges(); 9 10 issue.GenerateSerialNumber(); 11 if (!string.IsNullOrEmpty(SettingContext.Instance.AdminOpenIds)) 12 { 13 var name db.Users.GetName(userId); 14 var totalPendings db.Issues.Count(x x.Status IssueStatus.None x.IsDeleted false); 15 var adminOpenIds SettingContext.Instance.AdminOpenIds.Split(,); 16 foreach (var openId in adminOpenIds) 17 { 18 var message new PendingProcessTemplateMessage(openId, issue, name, totalPendings); 19 db.WeixinScheduledMessages.Add(message.ToWeixinScheduledMessage()); 20 } 21 } 22 db.SaveChanges(); 23 } 24 }