Why Comments Can Be Harmful and How to Adopt a Zero‑Comment Policy

You can randomly pick a few commented sections in your current project and check whether the comments suffer from one of two problems: inaccurate naming or methods longer than 50 lines.

If the code has neither issue yet still contains comments, ask whether the comment is truly necessary.

Comments are the devil

This provocative view may be hard to accept at first, but it has been voiced for years and is gaining recognition. An experienced US client once told the author in 2011 that “good code does not need comments,” because the mixed Chinese‑English comments were hard to understand.

Comments can make code harder to read. For example, a property with an XML comment:

/// <summary> /// 管理员是否可以审核该申请 /// </summary> public bool IsAudit { get; set; }

Replacing “Is” with “Can” would make the comment unnecessary.

Writing comments often leads to lax naming discipline and longer methods, which reduces overall code quality. Relying on comments for understanding means the code itself becomes unreadable when traversed across many classes.

Therefore, the claim that “comments make code easier to read” is untenable.

Not writing a single comment? Impossible!

Many developers feel this is impossible because complex business logic or mixed‑language naming sometimes forces a comment. The author acknowledges the dilemma but notes that their team has successfully practiced zero‑comment coding since 2012 across multiple projects, improving quality.

How to achieve a zero‑comment codebase

Force yourself not to write comments.

Keep each method under 50 lines and let the method signature describe its purpose.

Avoid careless variable naming.

Below are two code snippets without comments; try to guess their purpose.

1. Search example

public PageResult Search(IssueSearchCriteria criteria, PageRequest request) { using (var db = base.NewDB()) { return db.Issues .WhereByAssignee(criteria.AssignedUserId) .WhereBySupervisor(criteria.SupervisorUserId) .WhereByCategory(criteria.CategoryId) .WhereBySearchStatus(criteria.Status) .WhereDateRange(criteria) .WhereNotDeleted() .WhereByKeyword(criteria.Keyword) .ToDtos() .OrderByDescending(x => x.CreatedTime) .ToPageResult(request.PageIndex, request.PageSize); } }

2. Update example

public void Submit(Guid userId, string content, string text, double lng, double lat, string address) { using (var db = base.NewDB()) { var issue = new Issue(userId, content, text, lng, lat, address); db.Issues.Add(issue); db.AddIssueLog(IssueLog.CreateOnSubmit(issue.Id, db.Users.GetNickName(userId))); db.SaveChanges(); issue.GenerateSerialNumber(); if (!string.IsNullOrEmpty(SettingContext.Instance.AdminOpenIds)) { var name = db.Users.GetName(userId); var totalPendings = db.Issues.Count(x => x.Status == IssueStatus.None && x.IsDeleted == false); var adminOpenIds = SettingContext.Instance.AdminOpenIds.Split(','); foreach (var openId in adminOpenIds) { var message = new PendingProcessTemplateMessage(openId, issue, name, totalPendings); db.WeixinScheduledMessages.Add(message.ToWeixinScheduledMessage()); } } db.SaveChanges(); } }

The zero‑comment rule has become a key milestone in the team’s quality improvement journey, and the author hopes sharing this practice can influence others.