Can Code Comments Help Reduce Technical Debt?

I personally believe that comments can indeed reduce technical debt, and I reject the view that careful design and highly readable code make comments unnecessary.

Not every requirement allows time for extensive design; many projects face tight deadlines. Even when time is available, after a few months the original author often cannot quickly understand the code without explanatory comments.

Without comments, recalling the original reasoning behind a piece of code is difficult; developers must step through each method, hoping for an "aha" moment, and older code (e.g., from a year or two ago) becomes practically unreadable.

Good comments should explain *why* a particular solution was chosen—such as why Redis was not used, why a database was preferred over a message queue, or why a random sleep is introduced. This rationale gives future maintainers confidence to modify the code, preventing the accumulation of technical debt.

Comments can become outdated, so they must be kept accurate. The author treats timely comment maintenance as a habit, updating them whenever requirements or steps change, viewing this responsibility as part of a programmer’s duty.

/**
 * 门店收货单处理流程
 */
private void processReceiveDocs(ReceiveCommand command) {
    // 收货单存储到数据库
    Long docsId = receiveDocsDomainService.submitReceiveDocs(command);

    // 统配到店的单据需要随机延迟1-10秒后再执行后续操作,因为存在部分收货场景,库存中心同步到ERP系统偶发故障,暂时解决不了
    if (DeliveryTypeEnum.UNIFIED_DELIVERY.getCode().equals(command.getDeliveryMethod())) {
        randomSleep();
    }

    // 收货单同步到库存中心
    syncReceiveDocsToStockCenter(docsId);

    // 发布收货单已创建的事件
    eventPublisher.publishCreateEvent(docsId, STATISTICS_RECEIVE);
}

The above snippet includes Javadoc, inline comments that clarify the core business flow, and an explanation for the random sleep—illustrating what the author considers good commenting practice.

Summary points:

Maintain high‑quality comments alongside code; they are as important as writing clean code.

Writing and regularly updating comments is an effective way to reduce technical debt.