代码文档：初学者指南🎯

结论

在这篇博客中，我们将快速了解如何编写代码文档。在深入探讨如何正确地编写代码文档之前，我们先来了解一下为什么需要编写代码文档？

随着我们在技术行业或软件开发领域积累的经验越来越丰富，我们会发现阅读代码的时间远比开发代码的时间要多。这可能包括阅读自己代码的早期版本、评估团队中其他人的文档，或者分析第三方库的代码及其示例。

因此，我们意识到，为了减少理解代码所需的时间，我们的代码应该更具可读性和可维护性！我们将介绍一些技巧和窍门，帮助您提高代码的可读性和文档性。

1. 在代码中添加注释

在代码中添加注释的目的是提供对代码所做操作的可理解的描述。

注释代码时，请牢记以下几点：
a. 不要简单地复述代码的功能。b
. 描述 原因。代码为什么要这样做？业务假设或算法步骤是什么？
c. 格式化注释，以最大程度提高可读性。正确使用制表符，并在必要时留空格
。d. 尝试使用 VS Code 的工具/扩展。

例如GhostDoc和Add JSDoc 注释。

我个人更喜欢添加 JSDoc 进行评论，它非常容易使用。

查看MSDN 上有关撰写有效评论的这篇文章

2.编写测试用例：

大多数开发人员都会为其代码编写单元测试， 以确保代码正常运行。这有助于检测并防止将来出现错误。

本质上，测试用例为您提供了代码应如何运行的想法，我们可以确信这不会在生产中造成任何问题。

编写测试用例时，请使用特定于语言/框架的工具/库。我更喜欢使用Jest来编写 NodeJS 和 React 代码。它快速安全，并且可以轻松实现模拟和代码覆盖。

3.提供合适的git提交信息。

正确的 git 提交信息有以下好处：
a. 它使提出的拉取请求 (PR) 更加清晰
b. 它是团队内部有效调试的关键
c. 使跟踪实施更加容易

有一篇关于 Git 提交消息的精彩文章

如何写出好的提交信息

提示：在 git 提交信息中添加任务/问题 ID，这有助于识别推送的具体功能，并方便追踪。git 提交信息应使用祈使现在时。

例如#task_id commit_message #3201 添加谷歌登录

4. 维护正确的 Readme 文件

它是一份包含如何使用项目的指南的文档。通常它会包含如何安装和运行项目的说明。一份闲置的自述文件应该包含
以下内容：a. 项目标题
b. 项目描述
c. 如何安装和运行项目
d. 文件夹结构说明和挑战
e. 已知问题和鸣谢
f. 许可证和版本控制

用于创建一流 Readme 文件的扩展。：Markdown Preview Enhanced

5. 编写自文档化的干净代码

我把这一点留到最后是有原因的，因为我想强调这一点，它是最重要的一点。

开发人员在编写生产级代码时应始终牢记以下几点：

1. 创建一个逻辑且易于管理的文件夹结构（对于 React，请参阅可扩展应用程序的 React 项目结构最佳实践）
2. 在整个项目中遵循文件、变量和函数的有意义的命名约定
3. 避免冗余代码：确定哪些代码重复，并尝试通过传递变量参数使其通用化
4. 评论：有时开发人员会构建一个非常复杂的逻辑，几个月后我们才知道我们做了什么，但几乎记不清为什么这样做，所以最好在必要时写一些评论。
5. 格式化：提高代码可读性的方法之一是格式化代码，并在整个项目中遵循相同的约定/意图。我使用Prettier R 扩展进行格式化。
6. 经常检查代码：如果你每天写代码 8-10 个小时，试着抽出 1-2 个小时来检查代码，寻找改进点、优化点、处理复杂度（时间和空间）的问题，并记录代码。这将为你节省大量时间，并帮助你更好地成长。我个人更喜欢下午做这件事。

请参阅本书以更好地理解《清洁代码》。

结论

在本节中，我们研究了如何编写代码文档，这将帮助您使代码更具可读性和文档性。

• 向您的代码添加注释
• 编写测试用例
• 提供合适的 git 提交消息。
• 维护正确的自述文件
• 编写自文档化的干净代码

总的来说，还有许多其他方法来记录您的代码，使用您认为最好的方法！

如果这里遗漏了任何一点，请在评论部分告诉我们。