software development (cs2500) - lecture 15: javadoc and ... › shared › teach › a21291 ›...

Software Development

M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Software Development (CS2500)Lecture 15: JavaDoc and Coding Conventions

M.R.C. van Dongen

November 6, 2009


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Outline

Today we study:• The javadoc documentation mechanism.• Some important Java coding conventions.From now on you should use javadoc and make your code complyto the coding conventions.


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Generating Documentation with javadoc

javadoc is a tool for creating html documentation.Documentation is generated from comments in java programs.Comments are formatted in special style called doc comments.The documentation is generated by the javadoc program.

Unix Session

$ javadoc LuvelyClass.java


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Doc Comments

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>.*/


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Doc Comments

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, ….


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Tags

Tags are used to specify content and markup.Tags are case-sensitive and should start with @.

Java

/*** Basic print method.** @author Java Joe.* @param bar the thing to be printed.*/

public void printStuff( int bar ) {...

}


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Kinds of TagsBlock tags are of the form @⟨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." );}

}


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Some Existing Tags

@author: Author Entry.@param: Parameter Entry.

Java

/*** Compute length of a given list.** @param list The given list.* @param <T> The type of the elements in the list.* @return The length of the list.*/

int length( List<T> list ) …

@version: Version Entry.@return: Return Entry.


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Hyperlinks

Java

/*** {@link ⟨package⟩.⟨class⟩#⟨member⟩ ⟨text⟩}*/


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Proper Order

Java

/*** @param …* @return …* @exception …* @author …* @version …* @see …* @since …* @serial …* @deprecated …*/


M.R.C. van Dongen

Introduction

javadoc

Coding ConventionsFilesClasses and InterfacesIndentationCommentsDeclarationsStatementsWhite SpaceNaming ConventionsMethodsOther Practice

Acknowledments

For Monday

. . . . . .

Coding Conventions

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.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Coding Conventions

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


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Coding Conventions

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.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Most Importantly

Follow the conventions of your company and the person whosecode you’re modifying.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Files• Files should consist of sections which are separated by blanklines and comments.

• Files longer than 2000 lines should be avoided.• Javadoc comments should be used to document theclasses/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;


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Class and Interfaces: Structure

..1 package statement.

..2 import statements.

..3 javadoc 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 Methods.Implementation comments should be used where apropriate.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Classes and Interfaces


class Example { // Opening brace here....

} // Closing brace here.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Indentation

• 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.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Breaking Method CallsJava Coding Convention

call1( longExpr1, longExpr2, longExpr3,longExpr2, longExpr3 );

int var = call2( longExpr1,call3( longExpr2, longExpr3,

longExpr2, longExpr3 ) );


int var = call2( longExpr1, call3( longExpr2,longExpr3, longExpr2, longExpr3 ) );

int var = call2( longExpr1, call3( longExpr2,longExpr3,longExpr2,longExpr3 ) );


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Breaking Arithmetic Expressions


longVariable = longExpr1 + (longExpr2 - longExpr3)/ longExpr5;


longVariable = longExpr1 + (longExpr2- longExpr3) / longExpr4;


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Further Examples


if ((condition1 && condition2)|| (condition3 && condition4)) {

// Stuff}


if ((condition1 && condition2)|| (condition3 && condition4)) {// Stuff

}


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Further Examples


var1 = (condition) ? thisStuff : thatStuff;var2 = (condition) ? thisStuff

: thatStuff; // Clearer!var3 = (condition)

? thisStuff: thatStuff; // Also impossible to miss!


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

CommentsDon’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.//*/return 42;

}


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Declarations

Prefer having one declaration per line.


int one; // Comment about purpose of one.int two; // Comment about purpose of two.


int one, many[]; // Allowed, but don't do this.

Variable declarations should be aimed at minimising scope [Bloch,2008, Item 29].


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

One Statement Per Line

There should be no more than one statement per line.


thisVar ++; thatVar --;

Avoid the use of the comma operator.


thisVar ++, thatVar --;


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

The return Statement

Avoid parentheses for return statements (unless this is clearer).


return; // Allowed but not for this course....

return myLuvelyComputation( );...

return (condition ? thisValue : thatValue);


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

The if StatementAlways use braces for if statements.


if (condition1) {…

}if (condition2) {

…} else {

…}if (condition3) {

…} else if (condition4) {

…} …


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

The for Statement

Use braces for for statements with non-empty body.


for ( initialisation; condition; update ) {…

}

For for statements with empty body add semicolon as follows.


for ( initialisation; condition; update ) ; // empty body


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

The while Statement

Use braces for while statements with non-empty body.


while ( condition ) {…

}

For while statements with empty body add semicolon as follows.


while ( condition ) ; // empty body


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

The do-while Statement


do {…

} while ( condition );


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

White Space

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 improvereadability.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Blank SpacesBlank spaces should be used in the following circumstances:

• A keyword followed by a parenthesis:


while␣(condition) {…

}

• A parenthesis followed by a brace:


while (condition)␣{…

}

• After commas in argument lists.• Before and after binary operators (except .):


var1␣=␣var2␣+␣var3␣*␣var4␣/␣(var5.method( )␣-␣1);

• After the semicolons in the for statement:Java Coding Convention

for (start;␣condition;␣update) {…

}

• After a cast: ‘(int)␣(3 * Math.random( ))’.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Naming Conventions

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 adjectivesending in ‘able’.

Methods: 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 wordsseparated with underscores.

Variables: Variables should be short, yet meaningful nouns.The naming scheme is the same as for methods.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Methods

Methods should be short.Break methods in sub-method calls when they become longerthan, say, 40 lines.


M.R.C. van Dongen

Introduction

javadoc


Acknowledments

For Monday

. . . . . .

Other Coding Practice

To be announced.


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

Acknowledgements

The section about javadoc is partially based on [Lewis andLoftus, 2009, Appendix I].More information about javadoc may be found athttp://java.sun.com/j2se/javadoc/writingdoccomments.The section about coding conventions is based on [Sun, 1997].

Joshua Bloch.Effective Java.Addison-Wesley, 2008.John Lewis and William Loftus.Java Software Solutions Foundations of Program Design.Pearson International, 2009.Sun.Java code conventions, 1997.This document is freely availablefrom http://java.sun.com/docs/codeconv.

http://java.sun.com/j2se/javadoc/writingdoccomments

http://java.sun.com/docs/codeconv


M.R.C. van Dongen

Introduction

javadoc

Coding Conventions

Acknowledments

For Monday

. . . . . .

For Monday

Study the notes, study Pages 80–87 of the book, and carry out theexercises on Pages 92 and 93 of the Book.

software development (cs2500) - lecture 15: javadoc and ... › shared › teach › a21291 ›...

Documents