不

不要注释你的代码。你的第一反应是持不同意见，但请听我说完。重要

2025-05-25

不要评论你的代码

作为开发者，你的第一个本能是不同意，但请听我说完。

重要的

作为开发者，你的第一个本能是不同意，但请听我说完。

我并不是说注释全都不好。如果使用得当，注释确实非常强大，但它们并不能解决你的困境，事实上，它们可能会制造新的困境。
一段代码可以使用精心设计的算法、利用著名的设计模式或利用编程语言的革命性特性，出色地解决关键问题，同时依赖于在每一步都提供注释，但对于维护它的开发团队来说，这仍然是一个谜。为什么？！
一些开发人员往往更专注于编写浪费时间的注释，而不是重构代码本身。以下是一些您的团队最好不要使用的注释：

冗余注释

注释应该增加价值或描述原始逻辑，而不是翻译语法。如果代码写得好，就不需要额外的注释来叙述每一行的工作。

您可以清楚地看到，这里的评论是如此不必要，尤其是所有描述性命名。



 // The processor delay for this component.
 protected int processorDelay = -1;
Enter fullscreen mode Exit fullscreen mode

误导性评论

通往地狱之路往往是由良好的意图铺就的。作者可以出于各种正当理由添加不准确的注释，但这会让可怜的程序员浪费宝贵的调试时间。

this.closed例如，此处的方法在变为时不会返回true。只有当 为 时才返回this.closed；true否则，它会等待盲超时，然后如果仍然未关闭，则抛出异常。差异令人震惊！



// Returns when this.closed is true. Throws an exception on timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception
{
    if(!closed){
        wait(timeoutMillis);
        if(!closed)
            throw new Exception("MockResponseSender could not be closed");
    }
}
Enter fullscreen mode Exit fullscreen mode

强制性评论

有些强制性的注释可能根本没那么有用。注释不应该只是杂乱的。

这里的 javadoc很混乱。



/**
 * @param title The title of the CD
 * @param author The author of the CD
 */
 public void addCD(String title, String author) {
     CD cd = new CD();
     cd.title = title;
     cd.author = author;
     cdList.add(cd);
 }
Enter fullscreen mode Exit fullscreen mode

噪音评论

评论应该提供新的信息，否则它们只是我们习以为常的噪音。如果你忽略了一条评论，就意味着它本来就不应该存在。

该作者不仅写了不必要的评论，还忘记添加 catch 主体并留下了没有上下文的含糊不清的评论。



try
{
     // Continue normal flow
     doSomething();
}
catch(Exception e1)
{
     // Give me a break!
}
Enter fullscreen mode Exit fullscreen mode

函数或变量替换注释

复杂的代码行不需要注释，它需要的是重构或分解为更小的组件。

看看这个改述，很神奇吧？



// does the module from the global list <mod> depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { }
Enter fullscreen mode Exit fullscreen mode

重新表述




ArrayList moduleDependees = smodule.getDependSubsystems();

String ourSubSystem = subSysMod.getSubSystem();

if (moduleDependees.contains(ourSubSystem)) { }
Enter fullscreen mode Exit fullscreen mode




位置标记注释

用评论标记特定位置很少有用；将某些功能聚集在一个横幅下是有意义的，但我看不出这对每个功能有多大用处，一般来说它们实际上可能只是混乱。

承认吧你做到了 ;)




// Actions //////////////////////////////////
Enter fullscreen mode Exit fullscreen mode




归因评论

没必要用一些小的署名来污染代码。有很多源代码控制工具可以很好地记住谁在什么时候添加了什么。

毕竟我们都在遭受 Git 的指责，我感觉自己暴露无遗。
替代文本

注释掉的代码

注释掉的代码其实并不重要，可以删除。实际上，大多数源代码控制系统都会帮我们记住代码。我们再也不需要囤积那些没用的代码了。

还记得你第一次发现自己很粘人吗？




InputStreamResponse response = new InputStreamResponse();

response.setBody(formatter.getResultStream(), formatter.getByteCount());

// InputStream resultsStream = formatter.getResultStream();

// StreamReader reader = new StreamReader(resultsStream);

// response.setContent(reader.read(formatter.getByteCount()));
Enter fullscreen mode Exit fullscreen mode




非本地评论

注释应该描述其附近的代码。代码和注释之间应该有明显的联系。

不要在局部评论中提供不相关或系统性的信息。有趣的历史讨论或不相关的细节描述不属于评论。

重要的

本文并非鼓励大家放弃注释。注释是强大的工具，但要明智地使用它们并注重其质量。另外，永远不要忘记重构代码是关键。

参考

本文基于Robert C. Martin所著的《代码整洁之道：敏捷软件工艺手册》，这本书非常值得一读，是一本非常棒的书，能为你带来很多收获。

文章来源：https://dev.to/nadaelokaily/don-t-comment-your-code-5e9h
Devto 翻译
PREV
如何将 Django 连接到 ReactJs。设置 Django 后端。设置 React 前端。将前端应用程序连接到 Django 后端。注意
NEXT
通过创建旅游网站学习 GatsbyJS -1