顾名思义，注释就是对代码的解释。注释不需要运行，它是用来提高代码的可读性和可维护性的。不好的注释会使代码变得更难懂。下面就以Java 语言的注释语法为例来解释说明写好注释的基础原则。
三种注释类型和其注释风格
1.记录源代码版权和授权的注释
一般放在每一个源文件的开头，说明源代码的版权所有者，以及授权使用的许可方式，或者其他的公共信息。
使用一般的星号注释符（/-/），注释块的首行和尾行只使用星号注释符，中间行以缩进一个空格的星号开始，文字和星号之间使用一个空格。注释的每行长度限制，和代码块的每行长度限制保持一致。
/*
* Copyright (c) 2018, FirstName LastName. All rights reserved.
*/
一般来说，版权和授权信息是固定的。版权和授权信息是法律条款，除了年份，一个字都 不能更改。对于每个源代码文件，我们记得复制粘贴在文件开头就行。需要注意的是，如 果文件有变更，记得更改版权信息的年份（比如上例中的 2018）。
2.生成用户文档的注释
这部分用来生成独立的、不包含源代码的文档，比如Javadoc 。
这些文档帮助使用者了解软件的功能和细节，主要面向的是该软件的使用者，而不是该软件的开发者。 比如 Java 的 API 规范的文档。
这种注释一般使用 Javadoc 要求的格式，文档注释符 （/-*/），除了首行使用特殊的文档注释符（/），其他的格式和第一种风格保持一致。
/**
* A {@code Readable} is a source of characters. Characters from
* a {@code Readable} are made available to callers of the read
* method via a {@link java.nio.CharBuffer CharBuffer}.
*
* @since 1.5
*/
public interface Readable {
...
}
3.用来解释源代码的注释
这部分注释帮助代码的阅读者理解代码。
使用行注释符（//），每行长度限制，和代码块的每行长度限制保持一致。
// Verify that the buffer has sufficient remaining
private static void verifyLength(ByteBuffer buffer, int requiredLength) {
...
}
String myString; // using end-to-line comment
// This is a multiple line comment. This is a multiple
// line comment.
if (!myString.isEmpty()) {
...
}
如果一段代码不再需要，清理掉代码而不是保留这个注释掉的代码块。
不要在源代码里记录代码历史，那是代码版本管理系统该干的事情。
写好注释的几点原则
一个基本原则：注释是用来提高代码的可读性和可维护性的。 不要让注释偏离了这个原则，破坏了代码的逻辑和可读性。
1. 准确，错误的注释还不如不写注释。比如，当我们说编程语言时，一定不要省略“编程”这两个字。否则，就可能会被误解为 大家日常说话用的语言。这就是准确性的要求。
2. 必要，多余的注释浪费阅读者的时间。如果代码已经能够清晰、简单地表达自己的语义和逻辑，这时候重复代码语义的注释就是多余的注释。注释的维护是耗费时间和精力的，所以，不要保留多余的、不必要的注释。
3. 清晰，混乱的注释会把代码搞得很乱。注释和代码要能从视觉上清晰地分割，这样注释就不会破坏代码的可读性。
4.不要在代码里标注你想要做的工作和已经做过的工作。比如使用 TODO，记录代码 更改记录等等。这些信息会干扰代码的阅读者。
5.不要把代码的调试语句保留在提交的代码里。可以使用临时的调试语句，但是不要把代码的调试语句保留在提交的代码里。这些调试语句，既不容易维护，也不容易阅读。
建议使用英文注释
因为使用中文注释不是一个所有人都能接受的风格。一部分人，一部分公司，并不接受中文注释。特别是国际化的项目，比如说贡献给 Apache 的项目，就没有办法使用中文注释了。
除了接受度之外，汉字带来的真正困扰是会影响到编码风格的偏好。比如命名的问题，到底是应该使用拼音还是英文？ 由于代码命名只能使用 ASCII 字符，注释里的拼音、 英文、汉字混杂的问题该怎么处理？代码编辑时，字符的切换也是一个麻烦事。比如，空格使用汉字全角，编译器会报错，但是肉眼看不到，问题排查起来也很心累。
也不是不能使用汉字。面对国内的需求文档的时候。因为很多项目的需求文档一般是汉字书写的。程序的编码， 当然需要按照需求来。如果需求的引用还要翻译成英文，那就太麻烦了。
网友评论