Dokumentera program. Dokumentation. Dokumentation. Javadoc. Javadoc 2

Transkript

1 Dokumentera program Dokumentation 88 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 De andra i utvecklingstemet behöver info 89 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 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 så slutar den allmänna beskrivningen av metoden Javadoc (endast klasser och (endast klasser och (endast metoder och (endast sedan @serial eller API beskrivningen på nätet är uppbyggd med hjälp av javadoc För mer info se: javadoc/ 92 Vad kan behöva dokumenteras Exempel på delar som bör ingå: Användarhandledning Systembeskrivning Algoritmbeskrivning Lösningens begränsning Testkörningar Källkod Bör också se prydlig ut då det är den mest detaljerade formen av dokumentation. Olika delar vänder sig till olika läsare. 93

2 Användarhandledning 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. Viktigt för andra utvecklare. Större program är ofta inte helt triviala att bygga och ska ngn annan kunna göra det så behöver det dokumenteras. 94 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 (här passar ett eller flera UML-diagram). 95 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. Tex i form av pseudokod. 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. 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? Testkörningar Du måste testa din lösning. 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? Tänk på att tester kan göras på olika delar separat och på det färdiga prgrammet. 98 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- whileoch 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: 99

3 Jan Erik Moström Enumeration Uppräkningsbar typ Enumeration Man räknar upp alla värden som typen ska ha Tidigare innan detta dök upp i java användes heltalskonstanter (fortfarande finns en mängd klasser där detta används) ofta för uppgifter där man nu använder enums. Lite mer avancerade än motsvarigheten i C Innan enum Med 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: case SOUTH: case WEST: case EAST: default: public class Navigate public enum Direction NORTH, SOUTH, EAST, WEST ; void go( Direction dir ) switch( dir ) case NORTH: case SOUTH: case WEST: case EAST: Kortleksexempel 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) ); 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; 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] public String tostring( ) return rankvalue + " of " + suitvalue;

4 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(); 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; public enum Planet MERCURY (3.303e+23, e6), VENUS (4.869e+24, e6), EARTH (5.976e+24, e6), MARS (6.421e+23, e6), JUPITER (1.9e+27, e7), SATURN (5.688e+26, e7), URANUS (8.686e+25, e7), NEPTUNE (1.024e+26, e7), 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 = E-11; Inte en klass utan en enum!!! 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)); public double surfacegravity() return G * mass / (radius * radius); public double surfaceweight(double othermass) return othermass * surfacegravity(); Collections Mer om Collection classes 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 110

5 ArrayList List LinkedList List Collection Queue PriorityQueue Collection AbstractSequent... LinkedList AbstractList ArrayList Set HashSet TreeSet Vector Stack LinkedHashSet AbstractCollection AbstractQueue PriorityQueue HashMap SortedSet Queue AbstractSet HashSet TreeSet LinkedHashSet TreeMap Set Map SortedSet LinkedHashMap SortedMap 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 114 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) 115 Map klasserna Tabell Uppslagning av element kopplade till en nyckel Typen på värde och nyckel kan variera HashMap Implementation av en Hashtabell 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

6 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) 118 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 ); Java utan Eclipse 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 Kommandoradsparametrar Jar-filer 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 122 Används för att paketera ihop javafiler så att det blir lättare att distribuera Eclipse kan exportera ett projekt till en jarfil Kan göras exekverbara genom att man i jarfilen beskriver i vilken klass metoden main finns startas via java -jar jarfilnamn.jar 123