Dokumentera program. Dokumentation. Dokumentation. Javadoc. Javadoc 2

(1)

196

Dokumentation

Dokumentera program

• Viktigt att dokumentera program!

• Ett program används sällan endast av den som utvecklat den

– Användaren behöver få veta hur programmet fungerar

• Ett program underhålls inte alltid av den som skrivit det

– Den som ska underhålla programmet behöver info

• Ett program utvecklas ofta av många personer – Den De andra i utvecklingstemet behöver info

197

Dokumentation

• Dokumentation i form av kommentarer behövs i koden

• Kommentarer räcker dock inte (rätt jobbigt att alltid behöva läsa källkod)

• Läsning på en del av problematiken att man vill ha två olika typer av dokumentation som till stor del innehåller samma info:

Javadoc

198 199

Javadoc

• Speciella kommentarer som kan användas för att generera dokumentation av koden man har skrivit

• Eclipse har möjlighet att generera denna dokumentation

• /** startar en javadoc kommentar

• Måste skrivas innan en klass, attribut, konstruktor eller metod deklaration

• Första raden skall vara en kort förklaring av vad metoden gör

• Efter den första raden som börjar med @ så slutar den allmänna beskrivningen av metoden

200

Javadoc 2

• @author (endast klasser och interface)

• @version (endast klasser och interface)

• @param (endast metoder och konstruktorer)

• @return (endast metoder)

• @exception (även @throws sedan Javadoc 1.2)

• @see

• @since

• @serial (eller @serialField eller @serialData)

• @deprecated

• API beskrivningen på nätet är uppbyggd med hjälp av javadoc

• För mer info se: http://java.sun.com/j2se/

javadoc/

201

Vad kan behöva dokumenteras

• Exempel på punkter från vår rapportmall:

– Framsida

– Innehållsförteckning

– Åtkomst och användarhandledning – Problembeskrivning

– Systembeskrivning – Algoritmbeskrivning – Lösningens begränsning – Problem och reflektioner – Testkörningar

(2)

202

Framsidan

• Framsidan på din labrapport kan du utforma ganska fritt. Tänk bara på att den ska vara läsbar, och innehålla (minst) följande information:

• Ditt namn

• Din e-mail adress här på CS!

• Kursens namn samt vilken termin det är (t.ex. vt08)

• Vilken laboration det är

• Handledarens/handledarnas namn

• Datum

• Vilken inlämning det är (första/andra/uppsamling etc.)

• Lämna plats för kommentarer

203

Innehållsförteckning

• Viktigt då man snabbt vill hitta till ett visst avsnitt (dokumentationen av ett program är sällan något man läser från start till slut)

• Innehållsförteckningen ska innehålla alla rubriker i rapporten, och eventuellt en del underrubriker, beroende på hur rörigt det blir.

• Tänk på att innehållsförteckningen inte bör vara listad i innehållsförteckningen...

• Använd gärna de funktioner som finns för att generera innehållsförteckning automatiskt i de olika ordbehandlingsprogrammen

204

Åtkomst & användarhandledning

• Kan ibland delas upp i två avdelningar

• Hur kan någon komma åt ditt program (inkl källkod). Vad heter de olika filerna som programmet är uppbyggt av.

– Viktigt för alla

• Hur används programmet.

– Viktigt för användare av programmet

• Hur ska man gå till väga för att kompilera din källkod.

205

Problemspecifikation

• Beskrivning av vad uppgiften går ut på.

• Ska kunna ge en bild av uppgiften utan att man ska behöva läsa hela orginalspecifikationen

• Beskriv problemet med egna ord.

• Sammanfatta problemet .

• Hänvisa till orginalspecifikationen .

• Gör specifikationen att vissa antaganden måste göras? Ta upp dessa i sådana fall

• Har du gjort några utökningar av uppgiften?

Redovisa i sådana fall dessa.

206

Systembeskrivning

• Ska beskriva systemets interna uppbyggnad och struktur.

• Beskriv varje klass och syftet med denna och dess del av helheten.!

– För att beskriva klassen behöver man också beskriva tex de metoder som finns i den.

– Här kan det gå bra att använda sig av javadoc för att automatgenerera delar av beskrivningen (klistra inte in dessa i rapporten utan hänvisa istället till vart man kan hitta dessa).

• Beskriv relationer mellan klasser, med figurer och kommentarer till dessa.

207

Algoritmbeskrivning

• Om du har använt några icke självklara algoritmer, t.ex. en sorteringsalgoritm, en sökalgoritm eller något annat, ska du beskriva den/dem här.

• Lämpligt med en numrerad lista (i flera nivåer)

• Försök undvika att använda element som är direkt kopplade till koden, t ex variabelnamn och dylikt

• Syftet med detta avsnitt är att en läsare ska kunna få förståelse för hur en komplicerad del löses utan att behöva lusläsa kod och utifrån denna inse vad som händer

(3)

208

Algoritmbeskrivning

• Kort och koncist

• Entydigt

• Högnivåliknande syntax

1 Kontrollera att antalet personer är mindre än tio 1.1 Om antalet personer överstiger tio, avsluta med ett felmeddelande

2 För varje person:

2.1 Skriv ut personens namn med röd text 2.2 Skriv ut personens födelsenummer med blå text 2.3 Skriv ut personens adress med grön text 3 Vänta på att användaren trycker på tangenten N 4 Avsluta funktionen

209

Lösningens begränsningar

• Beskriver alla begränsningar som du kan komma att tänka på, eller har stött på under testningen.

• Du bör tala om alla de begränsningar som strider mot specifikationen.

• Nästan alla lösningar innehåller någon begränsning, tänk till lite bara.

• Hur kan/kunde begränsningarna undvikas?

210

Testkörningar

• Du måste testa din lösning innan du lämnar in den.

För att visa att du gjort det, och för att ge handledarna ett snabbt sätt att kontrollera att din lösning ser OK ut så bifogar man testkörningarna i rapporten.

• Tänk ut vettiga testfall. Vad kan tänkas vara svårt för programmet?

• Kommentera testfallen. Varför valde du detta testfall? Blev resultatet som det var meningen att det skulle bli?

211

Källkod

• Ordbehandlare har en tendens att misshandla källkod ganska rejält vad gäller indentering, stavning etc.

– Det finns vissa verktyg vars syfte enbart är att skriva ut källkod snyggt (t ex atp, a2ps och enscript)

• Ska vara utskriven med ett icke-proportionellt typsnitt, t.ex. Courier.

• Koden ska vara indenterad på ett konsekvent sätt

• Tänk på att koden ska se bra ut även på papper då ni skriver den.

• Koden ska vara kommenterad där det inte är klart vad du gjort.

• Varje metod föregås av kommentarer som beskriver dess syfte, in-/utdata o s v.

212

Källkod/Indentering

• Hur man formaterar sin kod

• Flytta alltid in all kod som står ett block 3-4 tecken

• Detsamma för enkel sats som hör till t.ex. if- while- och for- satser

• Tänk på att inte skriva för långa rader

• Om du måste bryta upp ett uttryck/sats p.g.a. att raden skulle ha blivit för lång så flytta in resten av uttrycket minst till positionen för starten av uttrycket/satsen

• Mer info se:

http://java.sun.com/docs/codeconv/ ₂₁₃

Övrigt

• Använd ett korrekt och formellt språk

• Sidhuvud och sidfot. Använd dessa, men ha inte för mycket information i dem. I sidhuvudet kan du t.ex.

ha ditt namn, datum, kursens namn och vilken laboration det är. I sidfoten kan du ha sidnumret.

• Tänk på att förstasidan inte bör vara numrerad eller ha samma sidhuvud som resten av rapporten.

• Läs igenom det du skrivit innan du lämnar det ifrån dig.

(4)

214

Mer om Collection classes

Johan Eliasson

Collections

• Ett antal nyttiga fördefinerade klasser som hanterar “mängder” av information

• Klasserna (och endel interface finns i java.util)

• Vi har redan tittat på Arraylist (och i mindre grad Vector)

Johan Eliasson Queue

Set

TreeSet HashSet

LinkedHashSet

SortedSet Collection

LinkedList

PriorityQueue List

ArrayList

Map

SortedMap HashMap

TreeMap

LinkedHashMap

Johan Eliasson AbstractCollection

AbstractList

AbstractQueue

AbstractSet Collection

ArrayList Vector AbstractSequent...

List

Queue

PriorityQueue

Set

LinkedList

Stack

HashSet TreeSet

LinkedHashSet

SortedSet

LinkedList

• I stort sett samma metoder som ArrayList och Vector

• Till skillnad från dessa ej implementerat mha array.

• Behöver inte utföra kopieringar vid utökning som dessa

• Tar ev en gnutta mer utrymme än en maxutnyttjad ArrayList

• För att komma åt ett värde annat än det första eller sista (via index) gör att vi måste

stega igenom värdena

²¹⁸

Set-klasserna

• Mängd

• Innehåller maximalt en förekomst av ett objekt

• Innehåller metoder för att lägga till värden kolla om ett visst värde finns och plocka bort värden

• Inget index för att komma åt värdena

• Kan gås igenom med en Iterator (eller nya for-loopen om man vill göra något med alla

värden i den)

²¹⁹

(5)

Map klasserna

• Tabell

• Uppslagning av element kopplade till en nyckel

• Typen på värde och nyckel kan variera

220

HashMap

• Implementation av en Hash tabell

• Ger väldigt snabb åtkomst till ett värde givet en nyckel (ungefär som arrayens index). Tar trots detta inte onödigt mkt utrymme

221

hashCode

• Metod i Object

• För att de olika hash-datatyperna bland

collection classes ska funka så måste man

omdefiniera metoden

int hashCode()

för nyckeltypen (denna metod bör i stort sett alltid omdefinieras om

equal

omdefinieras)

• hashCode()

ska ge tillbaka ett heltal som ska vara lika om objekten är lika (men måste inte nödvändigtvis vara olika om objekten inte är det (även om det är bra för

prestandan)

²²²

Johan Eliasson

import java.util.HashMap;

public class Demo7a {

public static void main( String[] argv ) {

HashMap<String, Integer> hi = new HashMap<String, Integer>();

hi.put( "apa", 12 );

hi.put( "banan", 23 );

hi.put( "dask", 239 );

int i = hi.get( "banan" );

System.out.println( i );

} }

Jan Erik Moström

Enumeration

Johan Eliasson

Enumeration

• Skandal att detta inte fanns i Java 1.0

• Uppräkningsbar typ

• Man räknar upp alla värden som typen ska ha

• Tidigare innan detta dök upp i java användes heltalskonstanter ofta för uppgifter där man nu använder enums

(6)

Johan Eliasson

Innan enum

public class Navigate { final public static int NORTH = 1;

final public static int SOUTH = 2;

final public static int EAST = 3;

final public static int WEST = 4;

void go( int dir ) { switch( dir ){

case NORTH:

// ...

break;

case SOUTH:

// ...

break;

case WEST:

// ...

break;

case EAST:

// ...

break;

default:

// ...

} } }

Johan Eliasson

Med enum

public class Navigate {

public enum Direction { NORTH, SOUTH, EAST, WEST };

void go( Direction dir ) { switch( dir ){

case NORTH:

// ...

break;

case SOUTH:

// ...

break;

case WEST:

// ...

break;

case EAST:

// ...

break;

} } }

Johan Eliasson

import java.util.Scanner;

import cards.Deck;

import cards.Card;

public class CardDemo {

public static void main( String[] args ) { Scanner in=new Scanner(System.in);

int numHands = in.nextInt();

int handSize = in.nextInt();

Deck d = new Deck();

for( int i = 0; i < numHands; i++ ){

System.out.println( d.getHand( handSize) );

} } }

4 5

[QUEEN of CLUBS, SIX of DIAMONS, JACK of HEARTS, FOUR of SPADES, FIVE of HEARTS]

[EIGHT of DIAMONS, JACK of DIAMONS, FIVE of CLUBS, NINE of SPADES, THREE of CLUBS]

[ACE of HEARTS, SEVEN of HEARTS, TEN of HEARTS, THREE of HEARTS, TEN of DIAMONS]

[KING of SPADES, NINE of DIAMONS, FOUR of CLUBS, SEVEN of DIAMONS, DEUCE of DIAMONS]

Kortleksexempel

Johan Eliasson

package cards;

public class Card {

public enum Rank { DEUCE, THREE, FOUR, FIVE, SIX, SEVEN, EIGHT, NINE, TEN, JACK, QUEEN, KING, ACE } public enum Suit { CLUBS, DIAMONS, HEARTS, SPADES }

private final Rank rankValue;

private final Suit suitValue;

Card( Rank rankValue, Suit suitValue ) { this.rankValue = rankValue;

this.suitValue = suitValue;

}

public Rank rank( ) { return rankValue;

}

public Suit suit( ) { return suitValue;

}

public String toString( ) {

return rankValue + " of " + suitValue;

} }

Johan Eliasson

package cards;

import java.util.List;

import java.util.ArrayList;

public class Hand { private List<Card> hand;

public Hand( List<Card> content ) { hand = content;

}

public String toString( ) { return hand.toString();

} }

Johan Eliasson package cards;

import java.util.ArrayList;

import java.util.Collections;

import java.util.List;

public class Deck {

private List<Card> myDeck;

public Deck( ) {

myDeck = new ArrayList<Card>( );

for( Card.Suit suit : Card.Suit.values( ) ){

for( Card.Rank rank : Card.Rank.values( ) ){

myDeck.add( new Card( rank, suit ) );

} }

Collections.shuffle( myDeck );

}

public Hand getHand( int nrOfCards ) {

List<Card> handCards = myDeck.subList( 0, nrOfCards );

Hand hand = new Hand( new ArrayList<Card>(handCards) );

handCards.clear();

return hand;

} }

(7)

Johan Eliasson public enum Planet

{

MERCURY (3.303e+23, 2.4397e6), VENUS (4.869e+24, 6.0518e6), EARTH (5.976e+24, 6.37814e6), MARS (6.421e+23, 3.3972e6), JUPITER (1.9e+27, 7.1492e7), SATURN (5.688e+26, 6.0268e7), URANUS (8.686e+25, 2.5559e7), NEPTUNE (1.024e+26, 2.4746e7), PLUTO (1.27e+22, 1.137e6);

private final double mass; // in kilograms private final double radius; // in meters

Planet(double mass, double radius) {

this.mass = mass;

this.radius = radius;

}

public double mass() { return mass; } public double radius() { return radius; } // universal gravitational constant (m3 kg-1 s-2) public static final double G = 6.67300E-11;

public double surfaceGravity() {

return G * mass / (radius * radius);

}

public double surfaceWeight(double otherMass) {

return otherMass * surfaceGravity();

} }

Inte en klass utan en enum!!!

Johan Eliasson

public class WeightDemo {

public static void main(String[] args) { Scanner in=new Scanner(System.in);

System.out.println(“Enter your earth weight”);

double earthWeight = in.nextDouble();

double mass = earthWeight/Planet.EARTH.surfaceGravity();

for( Planet p : Planet.values() )

System.out.println("Your weight on ” + p + “ is " + p.surfaceWeight(mass));

} }

234

Java utan Eclipse

235

Suns javaverktyg

• javac

– Kompilator

– Kommandot “javac MinKlass.java” producerar klassfilen MinKlass.class

• java

– Virtual Machine

– Används för att köra javaprogrammen – Ex:

• java MinKlass

• appletviewer

– Kan användas för att visa applets

236

Kommandoradsparametrar

• Metoden main kan ges argument i kommandot

> java ComLinArgs Jättekul

• Dessa värden kallas kommandoradsparametrar

• Argumenten betraktas som en lista av strängar

//Visar ett exempel på parametrar till programmet public class ComLinArgs

{

public static void main (String[] args) {

System.out.print("Första argumentet är : ");

System.out.println(args[0]);

}//main }//class ComLinArgs

237

Jar-filer

• Används för att paketera ihop javafiler så att det blir lättare att distribuera

• Eclipse kan exportera ett projekt till en jar- fil

• Kan göras exekverbara genom att man i jar- filen beskriver i vilken klass metoden main finns

– startas via java -jar jarfilnamn.jar