如何编写有意义的代码注释

在大多数情况下，您并不是唯一在同一项目或代码库上工作的人。这意味着其他人可能也会阅读您的代码并且必须理解它。

所以，您应该编写代码注释来帮助其他开发人员去理解你所写的代码。描述函数、函数背后的推理及其输入和输出的代码注释将加快其他开发人员的学习过程。特别是对于初级开发人员，这些信息在学习代码时会派上用场。

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

1. 文档注释——这些注释的主要目的是快速阐明文件或组件的用途。您可以在 `index` 文件的顶部写一个代码注释来解释组件的作用，而不是阅读组件的整个代码来了解它的作用。

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

‍3.逻辑注释 - 逻辑注释是函数内的注释，用于阐明复杂的代码路径。

最重要的是，逻辑注释通常会提供很多详细的信息。详细程度会造成更多混乱并降低代码的可读性。

代码注释：4 个最佳实践

这是代码注释的四个最佳实践的列表。

1.利用代码注释或标签

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

您应该做好以下代码标记：

@desc - 为您的函数写下描述

@param - 描述函数接受的所有输入参数。确保定义输入类型。

@returns - 描述返回的输出。确保定义输出类型。

@throws - 描述函数可以抛出的错误类型

@example - 包含一个或多个显示输入和预期输出的示例。

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

许多开发人员使用注释来描述他们的代码正在做什么。这不一定是错误的。但是，不要忘记包括创建特定功能或组件的原因。此信息称为上下文。上下文对于让开发人员更深入地了解功能或组件背后的设计决策至关重要。当其他开发人员想要对您的功能或组件进行更改时，此上下文至关重要。

您经常会看到在函数描述中使用函数名称的代码注释。

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

参考阐明功能或组件的其他代码注释或内部文档并不是一个好主意。如果开发者想快速扫描代码以获得更好的理解，代码注释应该清晰。

如果你认为你需要添加一个文档来阐明代码的目的，这是错误代码的危险信号。

4. 在写代码的同时写注释

在编写代码的同时编写注释听起来是很理所应当的，但许多开发人员违反了这条规则。

您可能会忘记在这种情况下编写的部分逻辑，从而导致代码注释质量降低。如果您在单个拉取请求上工作多天，最好在完成功能或模块时写注释。

代码评论是一门艺术吗？

如果您关心代码质量，请花时间编写有意义的代码注释。这需要一些练习，但可以很快学会。要记住的关键概念是在代码注释中添加上下文。描述你创建代码背后的原因，而不仅仅是表面的信息。