锐客网

  1. 首页 > 睿知 > it技术 > >

java编码代码规范 java编码规范和格式的要求( 九 )

IT技术标号


在注释里 ， 对设计决策中重要的或者不是显而易见的地方进行说明是可以的 ， 但应避免提供代码中己清晰表达出来的重复信息 。多余的的注释很容易过时 。通常应避免那些代码更新就可能过时的注释 。
注意：频繁的注释有时反映出代码的低质量 。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰 。
注释不应写在用星号或其java编码代码规范他字符画出来的大框里 。注释不应包括诸如制表符和回退符之类的特殊字符 。
5.1 实现注释的格式(Implementation Comment Formats)
程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line) 。
5.1.1 块注释(Block Comments)
块注释通常用于提供对文件，方法，数据结构和算法的描述 。块注释被置于每个文件的开始处以及每个方法之前 。它们也可以被用于其他地方 ， 比如方法内部 。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式 。
块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：
/*
* Here is a block comment.
*/
块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它 。
/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
*one
*two
*three
*/
注意：如果你不使用indent(1)，就不必在代码中使用/*-，或为他人可能对你的代码运行indent(1)作让步 。
参见"文档注释"
5.1.2 单行注释(Single-Line Comments)
短注释可以显示在一行内，并与其后的代码具有一样的缩进层级 。如果一个注释不能在一行内写完，就该采用块注释(参见"块注释") 。单行注释之前应该有一个空行 。以下是一个Java代码中单行注释的例子：
if (condition) {
/* Handle the condition. */
...
}
5.1.3 尾端注释(Trailing Comments)
极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释 。若有多个短注释出现于大段代码中，它们应该具有相同的缩进 。
以下是一个Java代码中尾端注释的例子：
if (a == 2) {
return TRUE;/* special case */
} else {
return isPrime(a);/* works only for odd a */
}
5.1.4 行末注释(End-Of-Line Comments)
注释界定符"//"，可以注释掉整行或者一行中的一部分 。它一般不用于连续多行的注释文本；然而 ， 它可以用来注释掉连续多行的代码段 。以下是所有三种风格的例子：
if (foo1) {
// Do a double-flip.
...
}
else {
return false;// Explain why here.
}
//if (bar1) {
//
//// Do a triple-flip.
//...
//}
//else {
//return false;
//}
5.2 文档注释(Documentation Comments)
注意：此处描述的注释格式之范例，参见"Java源文件范例"
若想了解更多，参见"How to Write Doc Comments for Javadoc" ， 其中包含了有关文档注释标记的信息(@return, @param, @see)：
若想了解更多有关文档注释和javadoc的详细资料，参见javadoc的主页：
文档注释描述Java的类、接口、构造器，方法，以及字段(field) 。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员 。该注释应位于声明之前：
/**
* The Example class provides ...
*/
public class Example { ...
注意顶层(top-level)的类和接口是不缩进的，而其成员是缩进的 。描述类和接口的文档注释的第一行(/**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐) 。成员，包括构造函数在内，其文档注释的第一行缩进4格 ， 随后每行都缩进5格 。

推荐阅读


上一篇：u盘上怎么打开jb文件，u盘里的文件怎么打开

下一篇：抖音开直播怎么分享屏幕，抖音直播如何共享手机屏幕