编写有意义的代码注释的工程师指南

在大多数情况下，您并不是唯一在同一项目或代码库上工作的人。这意味着其他人可以阅读您的代码并且必须理解它。对于您留下的代码注释也是如此。开发人员经常在没有太多上下文的情况下编写“快速而肮脏”的评论，让其他开发人员对您要说的内容一无所知。这是一种糟糕的做法，只会造成比澄清事情更多的混乱。所以，是的 - 您应该为编写有意义的代码注释来帮助其他开发人员而烦恼。描述函数、函数背后的推理及其输入和输出的代码注释将加快其他开发人员的学习过程。特别是对于初级开发人员，这些信息在学习代码时会派上用场。

另一方面，代码注释引导我们讨论是否应该编写它们？有一大群开发人员主张反对编写代码注释。原因是代码应该是不言自明的。如果其他开发人员无法通过查看代码来理解您的代码的用途，那么它就是糟糕的代码。这可能是真的，但想想代码注释所需的小工作以及它返回的潜在好处。代码注释对于促进任何开发人员（尤其是初级开发人员）的入职流程都很有价值。对技术感兴趣朋友可以加这个扣扣2779571288交流。

让我们来看看不同类型的代码注释。

不同类型的代码注释

1. 文档注释- 这些注释的主要目的是快速阐明文件或组件的用途。您无需阅读组件的整个代码来了解它的作用，而是可以在 index 文件的顶部包含一个代码注释来解释该组件的作用。我不是这种类型的代码注释的忠实粉丝，因为它们会使您的代码非常嘈杂。我认为这些类型的架构评论应该存在于您的内部文档中，您可以在其中集中维护和讨论项目的架构。然而，对于开源项目，它确实带来了指导想要为项目做出贡献的人的价值。

2. 函数注释——函数注释是最有用的注释类型，可以自动生成多种语言。它们描述了函数的用途、它接受的参数以及它生成的输出。通常只描述公共函数就足够了，因为使用您的代码的开发人员不会与私有函数交互。
   

3. 逻辑注释——逻辑注释是函数内的注释，用于阐明复杂的代码路径。您可能已经猜到了，这是一种明显的代码异味或技术债务，表明您的代码过于复杂。最重要的是，逻辑注释通常提供太多详细信息。详细程度会造成更多混乱并降低代码的可读性。这是一个过于详细的代码注释示例。
   

代码注释：4 个最佳实践

下面列出了代码注释的四个最佳实践。

1. 使用代码注释或标签
许多编程语言定义了代码注释标准。Java 使用Javadoc，而 JavaScript 使用许多文档生成工具支持的JSDoc代码注释系统。

对于函数，您应该包含以下代码标记：

• @desc - 为您的函数写下描述
• @param - 描述函数接受的所有输入参数。确保定义输入类型。
• @returns - 描述返回的输出。确保定义输出类型。
• @throws - 描述函数可以抛出的错误类型
• @example - 包含一个或多个显示输入和预期输出的示例

下面是Lodash 代码中chunk 函数的一个例子。

2. 写下你为什么要做某事

许多开发人员使用注释来描述他们的代码正在做什么。这不一定是错误的。但是，不要忘记包括创建特定功能或组件的原因。此信息称为上下文。上下文对于让开发人员更深入地了解功能或组件背后的设计决策至关重要。当其他开发人员想要对您的功能或组件进行更改时，此上下文至关重要。您经常会看到在函数描述中使用函数名称的代码注释。正如您可能已经猜到的那样，这样的评论不会增加价值。上下文是指添加您无法从函数名称或其输入变量中提取的信息。下面你会看到一个没有上下文的代码注释的坏例子。

专业提示：尝试使用免费的Stepsize VSCode 扩展为技术债务、重构或 TODO 添加代码上下文。

3. 不要参考其他文件或评论

参考阐明功能或组件的其他代码注释或内部文档并不是一个好主意。如果开发者想快速扫描代码以获得更好的理解，代码注释应该清晰。您不想花时间搜索其他代码注释或阅读大量设计文档。如果您认为需要添加文档来阐明代码的用途，则这是错误代码的危险信号。

4. 写代码的同时写注释

在编写代码的同时编写注释听起来很明显，但许多开发人员违反了这条规则。我自己也为此感到内疚。在某些情况下，我在编写任何代码注释以提交我的拉取请求以供审查之前完成了我的代码。您可能会忘记在这种情况下编写的部分逻辑，从而导致代码注释质量降低。如果您在单个拉取请求上工作多天，则尤其如此。最好在完成功能或模块时写注释。

代码评论是一门艺术吗？
如果您关心代码质量，请花时间编写有意义的代码注释。这需要一些练习，但可以很快学会。要记住的关键概念是在代码注释中添加上下文。描述您创建代码背后的原因，而不仅仅是表面信息。开发人员不需要“什么”，因为他们可以阅读您的代码、输入参数和输出以更好地理解代码。请记住使您的代码注释尽可能简洁。你不想花更多的时间写代码注释而不是写代码。对技术感兴趣朋友可以加这个扣扣2779571288交流。