If you need to copy, spread, please attach this statement, thank you. Original source: http://java.sun.com/docs/codeconv/html/codeconvtoc.doc.html, the translation source: http://morningspace.51.net/ ,moyingzz@etang.com
(Continued) 5 Notes (Comments)
The Java program has two types of annotations: Implementation Comments and Documents (Document Comments). Realizing comments are those who have seen in C , use /*...*/ and // definitions. Document Note (known as "DOC Comments") is a unique java and is defined by / the / **.... Document comments can be converted to an HTML file through the JavaDoc tool. Realize comments to comment code or implement detail. Document Note describes the code from the perspective of the IMPLEMentation-Free. It can be read by those developers who have no source code. Note Should be used to give a summary of the code and provide additional information provided by code itself. Note Should only include information related to the reading and understanding procedures. For example, information such as how the corresponding packet is established or in which directory should not be included in the comment. In the comment, it is possible to explain the important or not obvious place in design decisions, but it should be avoided. Excessive annotations are easy to obsolete. It is usually avoided that the code updates may be more comments. Note: Frequent comments sometimes reflect the low quality of the code. When you feel forced to add anything, consider rewriting the code clearer. Comments should not be written in the big boxes drawn in an asterisk or other character. Note Should not include special characters such as patriant characters and backfall.
5.1 Implementation Comment Formats (IMPLEMENTATION China
The programs can have four things that implement annotations: block, single-line, tail, and end-of-line.
5.1.1 Block Comments (Block Comments)
Block comments are typically used to provide descriptions for files, methods, data structures, and algorithms. Block comments are placed at the beginning of each file and before each method. They can also be used elsewhere, such as internal interior. Block note inside features and methods should have the same indentation format with the code they described. The first block of the block should have a blank line, which is used to discrolize block annotations and code, such as: / *
* Here is a block Comment.
* /
Block comments can begin with / *, so that Indenter can identify it as the beginning of a code block without rearing it. / * -
* Here Is A Block Comment with Some Very Special
* Formatting That I Want Indent (1) To ignore.
*
* One
* TWO
* Three
* /
Note: If you don't use Indent (1), you don't have to use / * -, or to run Indenter for others in your code. See "Document Notes"
5.1.2 Single-line Comments (SINGLE-LINE Comments)
Short comments can be displayed in one line and have the same indented level with the subsequent code. If a note cannot be written within one line, it will be used (see "Block Comment"). There should be an empty line before a single line comment. The following is an example of a single-line annotation in a Java code: if (condition) {
/ * Handle the condition. * /
...
}
5.1.3 Tail Note (Trailing Comments)
The extremely short comment can be located in the same row with the code they want, but there should be sufficient blank to separate the code and comments. If there is a plurality of short comments appear in large segment code, they should have the same indentation. The following is an example of the tail end annotation in a Java code: if (a == 2) {return true; / * special case * /
} else {
Return isprime (a); / * Works Only for ODD A * /
}
5.1.4 Wing Note (End-of-Line Comments)
Comment default "//", you can comment out part of the row or a line. It is generally not used for annotation text; however, it can be used to comment out of the continuous multi-line code segment. The following is an example of all three styles: if (foo> 1) {
// Do a double-flip.
...
}
Else {
Return false; // explain why here.
}
// if (bar> 1) {
//
// // do a triple-flip.
// ...
//}
// else {
// Return False;
//}
5.2 Document Notes (Documentation Comments)
Note: See "Java Source File Example" here, see "How to Write Doc Comments for Javadoc", which contains information about document comment tags (@return, @Param @see): http://java.sun.com/javadoc/writingdoccomments/index.html To learn more about document comments and javadoc, see Javadoc Home: http://java.sun.com /javadoc/index.html Document Note Description Java class, interface, constructor, method, and field (field). Each document comment will be placed in the comment delimiter / **...*/, a comment corresponds to a class, interface or member. This comment should be before: / **
* The Example Class Provide ...
* /
Public class example {...
Note that the top-level and interfaces are not indent, and their members are indent. The first row (/ **) describing the document annotation of the classes and interfaces does not need to be indented; the subsequent document comments are indented in each row (align the asterisk). Members, including constructor, the first line of its document comments indent 4 grids, and then indent the 5 grid per line. If you want to give information about classes, interfaces, variables, or methods, and this information is not suitable for writing in the document, you can use the implementation block annotation (see 5.1.1) or tightly follow the separate note behind the declaration (see 5.1.2). For example, the details of a class implementation should be placed in a block annotation that keeps followed by the class declaration, not in the document comment. Document comments cannot be placed in a definition block of a method or constructor, since Java will associate the first declaration after the document comment is associated with it.
6 Declarations
6.1 Number per line declared
Recommend a row of a statement, because it is to write a comment. That is, int discount; // Indentation Level
Int size; // size of table
To be better than, int level, size; do not place a declaration of different types of variables in the same line, for example: int foo, fooarray []; // WRONG! Note: In the above example, put it between the type and the identifier A space, another alternative way is to use tab: int level; // indeentation level
Int size; // size of table
Object CurrenTry; // Currently Selected Table Entry
6.2 Initialization
Try to initialize while declaring local variables. The only reason not to do this is that the initial value of the variable depends on some previous calculations.
6.3 Layout (Placement)
The variable is declared at the beginning of the code block. (A block refers to any code that is included in the middle of braces "{" and "}".) Do not declare when the variable is used for the first time. This will make the programs that are not concentrated, and the transplantability of the code is hindered in this scope. Void mymethod () {
INT INT1 = 0; // Beginning of Method Block
IF (Condition) {
INT INT2 = 0; // Beginning of "if" block
...
}
}
One exception to this rule is the index variable for the FOR cycle (INT i = 0; I Avoid a local variable that covers a variable of the previous declaration. For example, do not declare the same variable name in the internal code block: int count; ... mymethod () { IF (Condition) { INT count = 0; // avoid! ... } ... } 6.4 Category and Interface Declaration (Class and Interface Declarations) When writing classes and interfaces, you should follow the following format rules: - The left parentheses before the method name and its parameter list "(" Do not have spaces - left braces "{" is located at the end of the declaration statement - Right Big Bouth "} "Another line, aligned with the corresponding statement statement unless it is an empty statement,"} "should follow" {"Class Sample Extends Object { INT IVAR1; INT IVAR2; Sample (int i, int j) { Ivar1 = i; Ivar2 = j; } Int emptymethod () {} ... } - Method and method separation 7 statement (statements) 7.1 Simple STATEments Each line contains a statement, for example: Argv ; // Correct Argc -; // Correct Argv ; argc--; // avoid! 7.2 Composite Statements (Compound Statements) The composite statement is a statement sequence contained in braces, such as "{statement}". For example, the following paragraphs. - Included in which the statement should be compained in a hierarchy - left braces "{" should be located at the end of the initial line of the complex statement; the right braces "}" should be partially row and composite statement . - Brackets can be used for all statements, including a single statement, as long as these statements are part of the IF-ELSE or FOR control structure. This makes it easy to add a statement without worrying to introduce bugs due to adding parenthesis. 7.3 Return statement (Return Statements) A returnis statement with a return value does not use parentheses "()" unless they make the return value more prominent in some way. Return; Return mydisk.size (); RETURN (SIZE? SIZE: DEFAULTSIZE); 7.4 IF, IF-ELSE, IF ELSE-IF ELSE statement (IF, IF-ELSE, IF ELSE-IF ELSE STATEMENTS) The IF-ELSE statement should have the following format: if (condition) { STATEMENTS; } IF (Condition) { STATEMENTS; } else { STATEMENTS; } IF (Condition) { STATEMENTS; } else if (condition) { STATEMENTS; } else { STATEMENTS; } Note: The IF statement is always enclosed in "{" and "}" to avoid the use of the following format: if (condition) // avoid! This OMITS the bracs {}! STATEMENT; 7.5 for statement (for Statements) A FOR statement should have the following format: for (Initialization; Condition; Update) { STATEMENTS; } An empty FOR statement (all work is completed in initialization, conditional judgment, update clause) should have the following format: for (Initialization; Condition; Update); When using a comma in the initialization of the for statement or in the update clause, avoiding the use of three variables, resulting in complexity. If necessary, use a separate statement before the FOR cycle (for the initialization subsis) or the FOR cycle (for the update clause). 7.6 While Statement (While Statements) A While statement should have the following format while (condition) { STATEMENTS; } A empty While statement should have the following format: while (condition); 7.7 Do-While Statement (Do-While Statements) A Do-While statement should have the following format: do { STATEMENTS; WHILE (condition); 7.8 Switch statement (Switch Statements) A Switch statement should have the following format: switch (condition) { Case ABC: STATEMENTS; / * Falls through * / Case Def: STATEMENTS; Break; Case XYZ: STATEMENTS; Break; DEFAULT: STATEMENTS; Break; } Whenever a CASE is executed down (because there is no BREAK statement), you should usually add a comment at the location of the BREAK statement. In the sample code above, comments / * falls through * /. 7.9 try-catch statement (Try-catch statements) A try-catch statement should have the following format: try { STATEMENTS; } catch (exceptionclass e) { STATEMENTS; } Behind a try-catch statement is also followed by a Finally statement, regardless of whether the TRY code block is successfully implemented, it will be executed. Try { STATEMENTS; } catch (exceptionclass e) { STATEMENTS; } finally { STATEMENTS; }
