Java Coding style guide 1. Java. Coding Style Guide. (July 2015)

Transcription

1 Java Coding style guide 1 Java Coding Style Guide (July 2015) This coding style guide provides advices how to design and document your software so that your source code is easier to read, to debug, to maintain, and to port to other environments. Such rules are probably not essential for very small programs which you implement in your programming courses at the university, but are mandatory if you implement large programs in a company. Many companies have their specific coding styles so that their programs have a unique appearance on the one hand (independent of the style of a particular programmer) and can at least be partially reused in other projects in an easy way on the other hand (cost savings). Every computer scientist has to face such rules sooner or later, so that you will learn to deal with a coding style guide in my courses. My rules restrict the freedom of a programming language in a reasonable way and force not necessarily required language constructs to make your program less errorprone and easier to read. Your source code must comply with and respect all listed rules and recommendations. Your program will be marked with failed (5.0), if a significant amount of it doesn t comply with my rules.

2 Java Coding style guide 2 1) Every file starts with a header with the following structure: / Description of the content of the file and important remarks. File: <filename> Author: <name> Date: <...> Version: <version number> History: <WHO has modified / added WHAT and WHEN> Place new entries always at the top of the list before old ones. / You can omit Version and History for small programs. 2) Every Java class starts with a header which describes at least all its private and public data structures, all methods, and the purpose of the class. Each file owns at most one public class. 3) Every larger method starts with a header which describes at least its purpose, its input parameters, its return value, and all error conditions and side effects. Smaller methods (less than 10 lines of code) can be described in the header of the class. 4) Put meaningful comments into your source code which are not obvious from the source code itself, so that your program is easier to read and to understand. Examples: wrong: val = val + 1; / increment val / System.out.printf ("\n"); / print newline / useful: String hostaddr; / name or IP address / 5) Use the same language for all comments. In general, comments in English are shorter than comments in German. 6) A comment after a statement starts in column 41 and ends before column 72 (use the tabulator key!). Closing comment characters start in column 73 where necessary. All opening and closing comment characters are placed in the same column. Long comments (more than about 30 characters) are placed before the statement, are indented to the level of the statement that follows, and end before column 72. Set the tabulator to eight characters. Comments following statements on the same line can be written with / or //. All other comments will be written with /, //, or / (Javadoc comment). Remark: In general, source code is part of the documentation and will probably be printed on DIN A4 sheets of paper in Germany. A line can hold up to 75 characters, if you use 12 characters per inch (10 pt character size) and 3 cm left and 2 cm right margins. 7) All statements must end before column 72 as well. 8) Write block comments (multiline comments) in the following way: /... /... or... / / 9) Write your source code and comments at the same time. It s not allowed to write the code first without any comments and then add comments afterwards, when the program is working as expected. Usually there is no time to add comments afterwards due to new projects.

3 Java Coding style guide 3 10) Indent each new block with exactly two characters. Matching keywords and braces start in the same column. The opening brace of a new block can be placed on a new line below the first character of the above line or at the end of a line. You can choose which version suits you better, but your choice must be consistent across all of your programs All blocks must be embedded in braces, even if they contain only a single statement. Example: if (...) if (...) switch (...) statement(s); statement(s); case...: statement(s); else else break;... statement(s); for (...)... default: statement(s); statement(s); break; or (this style is better supported using indentation with Xemacs) if (...) if (...) switch (...) statement(s); statement(s); case...: else else statement(s); statement(s); for (...) break; statement(s); default: statement(s); break; 11) A method name or keyword followed by a parenthesis as well as items in a comma- or semicolon-separated list must be separated by a space character. Example: System.out.printf ("...", par1, par2,...); for (int i = 0; i <...; ++i) 12) Separate binary and ternary operators and operands with a space character. Example: x = a + b; z = ((x < y)? x : y); 13) Don t use too large statements and expressions, so that they are easy to read. 14) Structure expressions with parentheses (easier to read). The following expression while ((table[i][0]!= c) && (i < tab_len)) is easier to read than the following sufficient expression while (table[i][0]!= c && i < tab_len) or even the following necessary expression while(table[i][0]!=c&&i<tab_len). 15) Only one statement per line is permitted. 16) Avoid statements with side effects. 17) Declare variables as local as possible (modular design, information hiding). 18) Choose names carefully and explain them in a comment if necessary. A name shall point to its usage so that it is helpful in understanding the code. Structure names with the character _ or a mixture of capital and lower letters (CamelCase). Don t choose too long names,

4 Java Coding style guide 4 because they may make arithmetic expressions difficult to read. Special characters of a language, e. g., German umlauts (ä, ö, ü, ß), are prohibited (even within comments)! Example: numthreads / number of parallel threads / WAIT_TIME / waiting time before termination / 19) Class and interface names start with a capital letter and names for methods and variables with a lower letter. Names for constants contain only capital letters. The name of the class containing the method main () should end in Main (e. g., ProducerConsumerMain ). 20) Treat everything in the same way, i. e., write all comments in the same language, choose all names in the same language, and so on. 21) Avoid special solutions (use standard methods if available). 22) Try to program defensively (catch even impossible cases). Add for example a default-case to a switch-statement even if the current version of the program covers all possible cases. That way you will generally detect an error faster, if you extend your program later and forget to add a new case to the switch-statement as well. 23) Don t optimize too early! 24) Display a meaningful message (e. g., Sales (in Euro): or lower interval bound:), if your program needs input from the user. 25) Display a meaningful message which explains an error and the expected input, if you get an incorrect or erroneous user input, before you request the input once more. 26) You have to comment your source code and to provide a good documentation for it. Use a normal text editor or word processor, which is available at our university, for the documentation. 27) The documentation consists of a user manual and a software developer manual. The software developer manual can be created with Javadoc. 28) The user manual must be self-explanatory, so that you can use the program without knowledge of the other documentation or the source code. This manual completely describes the handling and operation of the program (including possible error messages). It is recommended that you add useful examples to the manual to make it understandable and easy to use. 29) The software developer manual must provide all necessary information to maintain the program (trouble-shooting and debugging, updates and enhancements, and so on) in acceptable time. You can assume that the user manual and source code are available so that you can refer to these documents. In general, the manual should cover the following topics: a) A complete description of all data structures and algorithms (variables, constants, tables, working areas, files, and so on). b) The layout of the system, e. g., a coarse flowchart, class diagrams, and so on. In general, you can learn all details directly from the source code. You can use graphical tools (e. g., UML diagrams, Nassi-Shneiderman diagrams, or flowchart diagrams) to visualize complex control structures. c) A description of the development environment: compiler version, special classes or packages, and so on. Make sure that you mention all specific features.

5 Java Coding style guide 5 30) You must show that your program solves the problem and works in an appropriate way (the compiler isn t allowed to report any warnings, even if you activate all warnings at the highest level). You must provide suitable examples (e. g., appropriate input data to show different behaviours or even errors) for the presentation of your program

6 Java Coding style guide 6 Example The following program implements algorithms to compute the greatest common divisor and the least common multiple of two natural numbers. The documentation is embedded in the files and can be generated with Javadoc. / You can automatically generate a documentation with "javadoc" if you use javadoc-style comments. The comments can contain HTML-code. <br><br> The documentation of a class, method, variable or constant (called "field" in Javadoc) must directly precede the corresponding statement. If you don't use packages you may see "<Unnamed>" in some places of the documentation. You can create a directory "doc-files" in each package directory containing images and complete HTML files. Javadoc will copy this directory with all files to the destination directory of your documentation so that you can use these files in your documentation (as you can see in the file "ComputeGcdOne.java"). Javadoc supports a lot more which you can read in the corresponding manual page or on the web.<br><br> This program determines the <b>greatest common divisor</b> (gcd) and <b>least common multiple</b> (lcm) of two natural numbers. The greatest common divisor can be determined with Euclid's algorithm. You can find a description of both algorithms on wikipedia or in the book from Knuth.<br><br> <table style="width:100%" summary=""> <tr> <td style="width:30%" align="left" valign="top"> Class file generation: </td> <td style="width:70%" align="left" valign="top"> <code>javac GcdLcmOneMain.java</code> </td> </tr> <tr> <td style="width:30%" align="left" valign="top"> Usage: </td> <td style="width:70%" align="left" valign="top"> <code>java GcdLcmOneMain</code> </td> </tr> <tr> <td style="width:30%" align="left" valign="top"> Documentation: </td> <td style="width:70%" align="left" valign="top"> <code>javadoc -d html_1 GcdLcmOneMain.java</code><br> <code>javadoc -d html_1 -author -version -private GcdLcmOneMain.java</code> </td> </tr> </table> <br>

7 Java Coding style guide <ol> <li><b>knuth, D.E.:</b> The Art of Computer Programming. Vol. 2: Seminumerical Algorithms. 2nd edition, Addison-Wesley, 1981, ISBN , pp (available: 3rd edition, 2003, ISBN ).</li> <li><b>unix / Windows:</b> javadoc -help</li> <li><b>unix:</b> man javadoc</li> <li><b>wikipedia:</b> <a href=" <a href=" <a href=" <br> S. 1.0 / / File: GcdLcmOneMain.java Date: / public class GcdLcmOneMain / Parse program parameters from the command args args[0] and args[1] should be natural numbers / public static void main (String args[]) int a, // value of 1st parameter b, // value of 2nd parameter result; // result of gcd (), lcm () ComputeGcdOne comgcd = new ComputeGcdOne (); ComputeLcmOne comlcm = new ComputeLcmOne (); a = 0; b = 0; // parse command line switch (args.length) case 2: // both numbers are available try a = Integer.parseInt (args[0]); catch (NumberFormatException e) System.err.println ("Input parameter error"); System.err.println (" \"" + args[0] + "\"" + " isn't an " + "integer value."); System.exit (0);

8 Java Coding style guide 8 try b = Integer.parseInt (args[1]); catch (NumberFormatException e) System.err.println ("Input parameter error"); System.err.println (" \"" + args[1] + "\"" + " isn't an " + "integer value."); System.exit (0); break; default: System.out.println ("I'm computing the greatest common " + "divisor and least common multiple"); System.out.println ("of two integer values."); System.out.println (" Usage: java GcdLcmMain " + "<1st number> <2nd number>"); System.exit (0); // check parameters if (a < 0) System.out.println ("Input parameter error"); System.out.println (" 1st number isn't positive. I use its " + "absolute value."); a = Math.abs (a); if (b < 0) System.out.println ("Input parameter error"); System.out.println (" 2nd number isn't positive. I use its " + "absolute value."); b = Math.abs (b); // compute greatest common divisor result = comgcd.gcd (a, b); System.out.println ("a: " + a + " b: " + b + " gcd (a, b): " + result); // compute least common multiple result = comlcm.lcm (a, b); System.out.println ("a: " + a + " b: " + b + " lcm (a, b): " + result);

9 Java Coding style guide 9 / Determine the <b>greatest common divisor</b> (gcd) of two natural numbers. The greatest common divisor can be determined with Euclid's algorithm. You can find a description of the algorithms on wikipedia or in the book from Knuth.<br><br> This algorithm uses an iterative solution.<br><br>... / / File: ComputeGcdOne.java / public class ComputeGcdOne / temporary value for swap operations or intermediate results / private int tmp; / This version of Euclid's algorithm uses a modulo operation. The original algorithm uses only subtractions and is less efficient. <br><br> <img src="doc-files/gcd.gif" a the first number for the greatest common b the second number for the greatest common the greatest common divisor / int gcd (int a, int b) while (b!= 0) tmp = a % b; a = b; b = tmp; return a; /... This algorithm uses a recursive solution.<br><br>... / / File: ComputeGcdRecursiveOne.java / public class ComputeGcdRecursiveOne /... / int gcd (int a, int b) if (b == 0) return a; else return gcd (b, a % b);

10 Java Coding style guide 10 / Determine the <b>least common multiple</b> (lcm) of two natural numbers. You can find a description of the algorithm on wikipedia or in the book from Knuth.<br><br>... / / File: ComputeLcmOne.java / public class ComputeLcmOne / Determine the smallest natural number which is a multiple of both parameters. You have used this technique already in school when you had to add fractions determining the least common denominator of both a the first number for the least common b the second number for the least common the least common multiple / int lcm (int a, int b) int gcd = (new ComputeGcdRecursiveOne ()).gcd (a, b); if (gcd!= 0) return Math.abs ((a b) / gcd); else return a b; You can define your own tags to make your comments more readable. package javadocexample; /... This version uses packages and self-defined tags. "javadoc" didn't work as expected when the self-defined tags were only defined in the argument <code>cd <package directory><br> javac <code>cd <package directory><br> java <code>cd <package directory><br> javadoc -tag mytag.compiling:pt:"class file generation:" -tag mytag.running:pt:"usage:" -tag mytag.documentation:pt:"documentation:" -tag mytag.todo:a:"to Do:" \@javadocexample/doc_cmds</code>... / / File: GcdLcmTwoMain.java /...