type
status
date
slug
summary
tags
category
icon
password
Edited
Sep 15, 2022 01:16 PM
Created
Aug 22, 2022 01:56 PM
注释冗余
我们往往会写一段注释来说明“这是什么”。比如：
但是这段代码本身的意思就很清楚了，再附上注释就有点多余了。
所以我们应该将其剔除。
那么，这段代码是不是就方便阅读了呢？其实，咱们还能更进一步：
这样你感觉如何？相比于最开始的那段代码，这段是不是就看得舒舒服服？
所以，可读的代码比可读的注释更重要。优先考虑让你的代码说话，实在不行，再附上简短、清晰的注释
如果你决定注释，那就不要只写一半。请尽量准确、完整、干净的将其写出。从长期来看，你一定会从中受益
注释规范1：使用像句子那样的注释
用句子能够保持注释意思的上下文的完整性，而像短语、缩写这类的注释可能每个人的理解都不同。
注释规范2：对于 API 应当编写文档
注释规范3：编写库级别的文档注释
一个库的注释文档是使用者了解该库的最佳方式，编写库的文档建议按如下方式进行：
- 一个简短的总结告知使用者这个库的用途。
- 介绍库中通篇用到的术语。
- 一组完整的使用该库 API 的示例代码。
- 链接相关重要或通用的类或方法。
- 为库中涉及到的外部引用提供访问链接。
注释规范4：保持合理的注释段落结构
注释规范5：上下文清晰的情况下不要重复介绍
注释规范6：在文档中提供示例代码
注释规范7：将需要解释的参数、返回值和异常通过语言组织起来
参考链接：
- 作者:JinSo
- 链接:https://jinso365.top/article/code-standards-comment
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。