Krav och praktiska råd inför inlämningsuppgifterna i PT2 Denna kurs har som mål att lära ut programmeringsteknik. Förutom att kunna lösa programmeringsproblemet man har ställts inför så har man fler krav på sig i ett verkligt programmeringsprojekt. Om man ser på hur man ska koda finns det många olika tillvägagångssätt. I kursen kommer vi att lägga vikten på att man skriver väldokumenterad, välstrukturerad och effektiv kod. Att lära sig skriva program tar flera år och man kommer att, om man är bra, finna sin egen väg till bra programmering. Det vi kommer att ställa som krav på kursen är att ni följer specifika kodkonventioner vad gäller indentering av koden, namngivning av variabler, paket, klasser och metoder. Till detta kräver vi att ni dokumenterar er kod på ett tillfredsställande sätt. 1. Kodkonventioner Det enda kravet på kodens struktur är att ni indenterar den. Ett nytt block ska indenteras med 2-4 mellanslag. 4 mellanslag är att rekommendera. Namnkonventioner är till för att ge programmeraren ytterligare information om vad som är vad i koden. Med hjälp av hur ordet ser ut kan man lätt sluta sig till vad dess egenskaper är t ex om det är en instansvariabel eller en konstant. De konventioner som vi ställer krav på att ni ska följa kommer till stora delar från Javaspråkets utvecklare, SUN Microsystems, och får sägas vara det man följer ute i (den seriösa) industrin. 1.1 Paket Paketnamn ska skrivas med små bokstäver. Vi kan komma att kräva att era uppgifter har specifika paketnamn. Vi rekommenderar att ni alltid använder ert användarnamn som paketnamn. ex: package se.uu.it.tein; Skälet till att man använder paketnamn är att java är byggt för att kunna återanvända kod. Man vill därför helst att all kod som skrivs har unika paket- och klassnamn för att undvika kollisioner. 1.2 Klasser Klassnamn börjar med stor bokstav och har versaler som ordavgränsare. Vidare ska klassnamnet ha ett prefix som är initialerna i ert namn. Skälet till denna konvention är enkel, man ser lätt varifrån klassen kommer. I koden finns oftast inte paketnamnen utskrivna. klassnamnens prefix ger då snabbt info om vartifrån den kommer och vem som har skrivit klassen. För Mattias Willman bli kan en klass ges namnet: ex: public class MWSort; 1.3 Metoder Metoder börjar alltid med liten bokstav och har versaler som ordavgränsare. ex: public void sortNumbers(int[] numbers); 1.4 Konstanter En konstant skrivs med stora bokstäver och har underscore som ordavgränsare. ex: public static final int NUMBER_OF_PASSES = 23; 1.5 Klassvariabler En klassvariabel ska börja med liten bokstav, ha versaler som ordavgränsare, samt ha prefixet "c". Prefixet ger direkt vilken utsträckning variabeln har, i detta fallet är variabeln den samma för alla instanser av klassen den defineras i. 1.6 Instansvariabler En instansvariabel ska börja med liten bokstav, ha versaler som ordavgränsare samt ha prefixet "i". 1.7 Lokala variabler En lokal variabel ska börja med liten bokstav och ha versaler som ordavgränsare. En lokal variabel har inge speciellt prefix men får ej börja på "i" eller "c" eftersom detta är prefixen för instans- och klassvariabler. Undantaget är enbokstavsnamn. ex: int sumOfParameters = 0; int i = 0; //OK! Enbokstavsnamn. int c = 0; //OK! Enbokstavsnamn. 2. Dokumentation Java har ett väl utvecklat stöd för dokumentation, kallat javadoc. I källkoden kan man ange taggar som talar om vilken sorts information man skriver. Den informationen extraheras och sammanställs sedan och läggs upp som html så att man snabbt kan se dokumentationen för en klass, utan att öppna den eller ens behöva källkoden. All kod som lämnas in på denna kurs ska ha klasser, metoder och variabler dokumenterade. 2.1 Klasser En klass har en header där man t ex beskriver klassens funktion,vad den löser för problem och teorin bakom den. Den kan se ut som: /** * This class implements the list interface as given in the article by * John Doe et al. guranteeing O(log n) runtime for all common operations. * */ public class MWSuperList implements List; Det första man ska lägga märke till är början på kommentarsblocket "/**". Den anger att det man skriver ska extraheras och läggas upp som dokumentation i javadoc Det man skriver i denna klassheader läggs upp som en allmän beskrivning av klassen. 2.2 Metoder Dokumentationen för en metod har strukturen /** * This method takes to integer arguments and returns the product of * the two. * @param arg1 The first argument * @param arg2 The second argument * @return The product of the two arguments. */ public int product(int arg1, int arg2) { return (int) arg1 * arg2; } Den första textbeskrivningen kommer att läggas upp som en allmän beskrivning av metoden. Den första taggen "@param" nanger att detta är namnet och beskrivningen av det första argumentet kommer. Den andra taggen "@param" beskriver det andra argumentet. Taggen "@return" visar att nu kommer beskrivningen av vad metoden returnerar. 2.3 Variabler När man definerar variabler kan man lägga till dokumentation. /** * This is the variable containing the number of passes done for creating * the table. */ public int iNumberOfPasses = 0; Dokumentationen av variabeln kommer att läggas upp i javadoc. Det finns många fler taggar som man kan lägga till, men vi kräver endast att dessa finns med. Javas egen dokumentation nyttjar javadoc. Bläddra igenom dokumentationen så ser ni verkligen nyttan av javadoc. Ni kan även läsa mer om javadoc i denna dokumentation. 3 Tips Det finns fällor som man lätt kan undvika med ett minimum av struktur i sitt projekt. Skapa en speciell katalog för källkoden för kursen. Skapa en katalog src/, för all källkod som ni kommer att skriva. Målet är att återanvända kod. Skapa en katalog build/, där ni kompilerar all kod. Man ska hålla källkod och kompilerad kod åtskilda för att undvika missöden. skapa en katalog lib/ där ni lägger externa bibliotek, t ex extra-paketet från Skansholms bok. Denna struktur hjälper att hålla reda på källkoden för projektet så det blir lättare att arbeta med den. Katalogträdet kan se ut som: pt2 | |-lab1 | | | +-doc | +-src | \-build | \-lib