Software Development (CS2500)

Transcription

1 (CS2500) Lecture 15: JavaDoc and November 6, 2009

2 Outline Today we study: The documentation mechanism. Some important Java coding conventions. From now on you should use and make your code comply to the coding conventions.

3 Generating Documentation with is a tool for creating html documentation. Documentation is generated from comments in java programs. are formatted in special style called doc comments. The documentation is generated by the program. Unix Session $ LuvelyClass.java

4 Doc Doc comments start with /** and end in */. Additional lines should start with *. The comments may contain html tags. Java /** * This is an <strong>example</strong>. */

5 Doc First line of each doc is automatically included in documentation. It should provide a concise description of what is documented. Doc comments are subdivided into descriptions and tags. Description: Provide overview of functionality of presented code. Tag: Tags specify address specific information. Includes information about author, version,.

6 Tags Tags are used to specify content and markup. Tags are case-sensitive and should start Java /** * Basic print method. * Java Joe. bar the thing to be printed. */ public void printstuff( int bar ) {. }

7 Kinds of Tags Block tags are of the tag name. They should be placed in tag section following main description. Inline tags are of the form {@ tag name more }. Java /** * Friendly class. * More information {@link #hello here}. */ public class Hello { public static void hello( ) { System.out.prinln( "hello world." ); } }

8 Some Existing Author Parameter Entry. Java /** * Compute length of a given list. * list The given list. <T> The type of the elements in the list. The length of the list. */ int length( List<T> list Version Return Entry.

9 Hyperlinks Java /** * {@link package. class # member text } */

10 Proper Order Java /** */

11 Why bother? 80% of the lifetime cost of software goes to maintenance. Others will have to read your code. Improves readability of your luvely code. Shipped code should be well packaged and clean.

12 Why bother? 80% of the lifetime cost of software goes to maintenance. Others will have to read your code. Improves readability of your luvely code. Shipped code should be well packaged and clean.

13 Why bother? 80% of the lifetime cost of software goes to maintenance. Others will have to read your code. Improves READABILITY of your L U V E LY code. Shipped code should be well packaged and clean.

14 Why bother? 80% of the lifetime cost of software goes to maintenance. Others will have to read your code. Improves readability of your luvely code. Shipped code should be well packaged and clean.

15 Most Importantly Follow the conventions of your company and the person whose code you re modifying.

16 should consist of sections which are separated by blank lines and comments. longer than 2000 lines should be avoided. Javadoc comments should be used to document the classes/interfaces, attributes, and methods. The import statements always go to the top of the file. If you need more than one import from a package, use the * notation: Java Coding Convention import java.util.*; Don t Try This at Home import java.util.treemap; import java.util.random;

17 Class and Interfaces: Structure.1 package statement..2 import statements..3 class-related comments..4 Class variables in increasing order of visibility: public, protected, and private..5 Instance variables in increasing order of visibility..6 Constructors..7. Implementation comments should be used where apropriate.

18 Java Coding Convention class Example { // Opening brace here.. } // Closing brace here.

19 Use four spaces as the unit for indentation. Use eight spaces if that improves readability. Avoid lines that are longer than 80 characters. Use the following rules for wrapping lines if they re too long: Break after a comma; Break before an operator; Prefer higher-level breaks to lower-level breaks; Align text with broken expression on previous line. Compound statements (blocks): The enclosed statements should be indented one more level. Opening brace: at end of line that begins block. Closing brace: indented at same level as line at start of block.

20 Breaking Method Calls Java Coding Convention call1( longexpr1, longexpr2, longexpr3, longexpr2, longexpr3 ); int var = call2( longexpr1, call3( longexpr2, longexpr3, longexpr2, longexpr3 ) ); Don t Try This at Home int var = call2( longexpr1, call3( longexpr2, longexpr3, longexpr2, longexpr3 ) ); int var = call2( longexpr1, call3( longexpr2, longexpr3, longexpr2, longexpr3 ) );

21 Breaking Arithmetic Expressions Java Coding Convention longvariable = longexpr1 + (longexpr2 - longexpr3) / longexpr5; Don t Try This at Home longvariable = longexpr1 + (longexpr2 - longexpr3) / longexpr4;

22 Further Examples Java Coding Convention if ((condition1 && condition2) (condition3 && condition4)) { // Stuff } Don t Try This at Home if ((condition1 && condition2) (condition3 && condition4)) { // Stuff }

23 Further Examples Java Coding Convention var1 = (condition)? thisstuff : thatstuff; var2 = (condition)? thisstuff : thatstuff; // Clearer! var3 = (condition)? thisstuff : thatstuff; // Also impossible to miss!

24 Don t Try This at Home public int answer( ) { /* Temporarily commented out for testing. /* * This gives you the answer. */ */ return 42; } Java public int answer( ) { /* Temporarily commented out for testing. // // This gives you the answer. // */

25 Don t Try This at Home public int answer( ) { /* Temporarily commented out for testing. /* * This gives you the answer. */ */ return 42; } Java public int answer( ) { /* Temporarily commented out for testing. // // This gives you the answer. // */

26 Prefer having one declaration per line. Java Coding Convention int one; // Comment about purpose of one. int two; // Comment about purpose of two. Don t Try This at Home int one, many[]; // Allowed, but don't do this. Variable declarations should be aimed at minimising scope [Bloch, 2008, Item 29].

27 One Statement Per Line There should be no more than one statement per line. Don t Try This at Home thisvar ++; thatvar --; Avoid the use of the comma operator. Don t Try This at Home thisvar ++, thatvar --;

28 The return Statement Avoid parentheses for return statements (unless this is clearer). Java Coding Convention return; // Allowed but not for this course.. return myluvelycomputation( );. return (condition? thisvalue : thatvalue);

29 The if Statement Always use braces for if statements. Java Coding Convention if (condition1) { } if (condition2) { } else { } if (condition3) { } else if (condition4) { }

30 The for Statement Use braces for for statements with non-empty body. Java Coding Convention for ( initialisation; condition; update ) { } For for statements with empty body add semicolon as follows. Java Coding Convention for ( initialisation; condition; update ) ; // empty body

31 The while Statement Use braces for while statements with non-empty body. Java Coding Convention while ( condition ) { } For while statements with empty body add semicolon as follows. Java Coding Convention while ( condition ) ; // empty body

32 The do-while Statement Java Coding Convention do { } while ( condition );

33 Adding white space generally improves readability. Add a blank line for the following: Between method definitions. Between local variable declarations and statements in a block. Before a block. Between logical sections inside a method to improve readability.

34 Blank Spaces Blank spaces should be used in the following circumstances: A keyword followed by a parenthesis: Java Coding Convention while (condition) { } A parenthesis followed by a brace: Java Coding Convention while (condition) { } After commas in argument lists. Before and after binary operators (except.): Java Coding Convention

35 Classes: Class names should be nouns in mixed case. First letter in each internal word should be upper case. Use whole words and avoid non-obvious acronyms. Interfaces: Ideally interfaces should be mixed case adjectives ending in able. : Method names should be verbs in mixed case. The first letter should be lower case. First letter of remaining words should be upper case. Constants: Class constants should be upper case with words separated with underscores. Variables: Variables should be short, yet meaningful nouns. The naming scheme is the same as for methods.

36 should be short. Break methods in sub-method calls when they become longer than, say, 40 lines.

37 Other Coding Practice To be announced.

38 Acknowledgements The section about is partially based on [Lewis and Loftus, 2009, Appendix I]. More information about may be found at The section about coding conventions is based on [Sun, 1997]. Joshua Bloch. Effective Java. Addison-Wesley, John Lewis and William Loftus. Java Software Solutions Foundations of Program Design. Pearson International, Sun. Java code conventions, This document is freely available from

39 Study the notes, study Pages of the book, and carry out the exercises on Pages 92 and 93 of the Book.