Projektbedömning
Här diskuterar vi hur projekten bedöms. Läs detta i förväg för att vara medvetna om vad ni behöver tänka på under projektets gång!
TL;DR: Översikt
-
Efter projektgranskning kan du få betyg (3-4-5 eller G-VG) eller komplettering. Under samma kalenderår kan du komplettera eller plussa enligt samma regler. Nästa år kan du behöva följa nya regler. Vi kan inte säga i förväg vilket betyg du kommer att få, precis som du inte kan veta i förväg exakt hur mycket du måste läsa på till en tenta.
-
Det finns ett antal grundläggande bedömningskriterier för att få godkänt. Det finns också högre krav för högre betyg, både allmänt (kvalitet, omfattning) och specifikt ("måste använda Javas stöd för resurser", "måste genomföra labb 5"). Vissa av kraven diskuterar vi i den löpande texten i flera avsnitt. Andra gäller varningar som enbart visas i kodanalysen. Viktigt att läsa detta för att inte få komplettering!
-
Det finns en sida med många specifika programmeringstips och saker att tänka på i projektet. Tipsen är starkt fokuserade på de problem vi faktiskt ser i inlämningar och är väl värda att läsas genom ordentligt för att öka chansen att du får ditt önskade betyg. Många problem som kan upptäckas automatiskt är borttagna från tipslistan då vi kan ge tipsen direkt i kodanalysen istället.
-
Det är mycket viktigt att ta kodanalysen på allvar. Vi får ganska många inlämningar med större mängder viktiga varningar och tvingas ge komplettering. Läs nedan om hur vi ser på varningar av olika styrka (SHOWSTOPPER, SEVERE, WARNING, ...) och på varningar som inte åtgärdas.
-
Vi har också vissa bedömningskriterier för projektrapporten.
Allmänt om projektbedömning
När du lämnar in ditt projekt kommer det att granskas i två omgångar, först av en handledare och sedan av examinatorn. Resultatet av bedömningen kan bli att:
-
Projektet blir godkänt. I TDDD78 och TDDE30 ges betyg 3-4-5. I 729A85 ges betyg G-VG.
Du kan också plussa (höja betyget) vid senare inlämningstillfälle genom att fortsätta arbeta med samma projekt. Detta gäller garanterat under årets inlämningsmöjligheter, som visas på deadlinesidan. När nästa kursomgång börjar kan du behöva följa nya regler!
-
Projektet behöver kompletteras vid senare inlämningstillfälle.
Komplettering kan behövas även om det är uppenbart hur man skulle ändra koden – för det är genom att göra som man både lär sig mest och visar att man kan, inte genom att förklara hur man kunde ha gjort.
Under årets inlämningstillfällen kan du fortsätta komplettera enligt årets regler och bedömningar. När nästa kursomgång börjar kan reglerna ändras.
Det tar ofta ett par timmar att bedöma och kommentera ett projekt, så det är omöjligt för oss att ge en fullständig bedömning i förväg.
Vilket betyg kommer jag att få?
Betyget du får ska vara en helhetsbedömning av ditt resultat under projektet och labb 5. För att bedömningen ska bli rättvis måste vi kunna ta hänsyn till väldigt många olika kriterier och väga in alla olika positiva och negativa aspekter som vi kan se.
Som student vill man så klart veta exakt vilka de här kriterierna är, men även om det går utmärkt att beskriva dem på en abstrakt nivå (exempelvis "lättförståelig kod"), går det inte att göra en uttömmande lista på alla sätt som man kan bryta mot dem (alla sätt att göra koden svår att förstå). Det går inte heller att ge en algoritm som talar om exakt när den inlämnade koden är precis tillräckligt lättförståelig för att inte ge komplettering. Det går definitivt inte att beskriva exakt när en svårförståelig lösning kan kompenseras av hög kvalitet på ett annat område. I slutet måste någon ändå göra en bedömning, speciellt med tanke på den enormt stora variationen vi har i de fria projekten.
Alltså måste detta fungera som på en tenta: Man får reda på vad som ingår i kursen och vilka områden man behöver arbeta med för att maximera chansen att klara tentan. När man studerar kan man inte veta exakt när man har lärt sig tillräckligt mycket för att få godkänt, eller när man har besvarat en fråga tillräckligt bra för att få full poäng. Man får jobba på till man tror man har klarat gränsen med rimlig marginal.
Men man får ändå en hel del hjälp, dels genom bedömningskriterierna nedan, dels genom kodanalysen.
Allmänna bedömningskriterier och krav
Vi vill bland annat att projekten ska visa upp följande. I ett senare avsnitt ger vi många tips på konkreta problem som kan uppstå i dessa områden. Vissa delar kan täckas av kodanalysen, medan andra inte kan analyseras automatiskt.
-
God användning av objektorientering och Java. Detta kan t.ex. handla om ärvning, polymorfism, inkapsling ("gömma" fält och andra implementationsdetaljer), med mera. Det kan också handla om att använda Javas klassbibliotek på ett bra sätt, framförallt i de delar som har diskuterats på föreläsningarna eller täcks av kodanalysen.
Ta alla chanser att programmera objektorienterat. Det behövs för att demonstrera att du har lärt dig begreppen som ingår i kursen och vet hur de ska användas. Detta är ju kursens mål! Om ett problem kan lösas på ett OO-sätt eller ett icke-OO-sätt ska du använda OO-lösningen, om den inte är uppenbart sämre.
-
Bra kodstruktur och organisation. Detta är viktigt eftersom programmering ofta går ut på att utöka och ändra existerande kod. Tid som läggs ner på att göra kod lättläst och välstrukturerad, och att dokumentera, är alltså inte bortslösad utan sparas in med råge i senare utvecklingsfaser. Slutmålet är därför inte bara att skapa ett program som åstadkommer rätt saker, utan att skapa ett program som gör på rätt sätt.
-
Lagom kortfattad och koncis kod. Genom att abstrahera, parameterisera och generalisera kan man skriva kortare, mer lättläst och mer utökningsbar kod utan onödiga upprepningar. Det är viktigt att lära sig det, inte minst för att det sedan gör att man också kan skriva koden snabbare!
Upprepa t.ex. inte kodrader när en loop hade gjort jobbet på ett enklare och bättre sätt. Ge namn till deluttryck som används många gånger, så att du slipper upprepa uttrycken om och om igen. Bryt ut hjälpmetoder i vissa fall. Fler tips kommer senare.
Alltför repetitiv och ineffektiv kod ger ofta komplettering, även när det inte gäller "exakt" upprepning. Gå genom all din kod och undersök om det finns något du tycker borde kunna uttryckas effektivare, kod där det känns som om du inte borde ha behövt skriva så mycket som du gjorde. Antagligen behövde du inte det!
-
Lättförståelig kod. Det bästa är om man kan skriva självförklarande kod, som inte ens behöver några kommentarer. Viktiga delar i detta är att ge bra och tydliga namn, att dela upp koden i rimligt stora metoder vars namn visar precis vad de gör, att undvika magiska konstanter, och att ge namn till deluttryck. Fler tips och detaljer kommer senare.
I många fall behövs så klart fortfarande kommentarer, inte minst för att förklara varför man gör något (på ett visst sätt). Fokusera då på det som behöver förklaras, inte på att mekaniskt kommentera enkla metoder med väl valda namn ("getX() returnerar x-koordinaten") bara för sakens skull.
Vi har sett extremt stora variationer i hur man kommenterar sina projekt. Vissa kommenterar alldeles för lite, medan andra ligger mycket över våra krav. Meningen är inte att varje fält, metod och kodstycke ska ha den perfekta och fullständiga beskrivningen, utan man behöver arbeta tillräckligt med kommentarerna för att den som läser koden ska få tillräckligt med information så man klart och tydligt förstår vad som händer och varför.
-
Robust kod. Här ingår att använda korrekt felhantering och att återhämta sig på ett bra sätt från exceptions och andra fel, speciellt sådana som kan uppstå på grund av användarens input.
Upptäckta fel får inte bara ignoreras. Med "upptäckta fel" menar vi dels undantag (exceptions) som fångas efter att de uppstår i egen kod eller andras kodbibliotek, dels andra typer av fel som man upptäcker på andra sätt, t.ex. genom att man själv kontrollerar om användaren ger felaktig input eller om en metod signalerar fel genom att returnera null.
Om ett fel beror på användarens input, t.ex. att användaren har matat in felaktig information i en dialogruta, valt en fil som inte kan öppnas eller har styrt en spelare utanför skärmen, ska det hanteras genom att användaren får en ny chans att ge korrekt input. För övriga fel får du, för betyg 3, skriva ut en stacktrace och avsluta programmet. Då demonstrerar du att du vet var felen kan uppstå och var de borde hanteras, och undviker många farliga följdfel.
Högre krav för betyg 4/5 diskuteras längre ner.
-
Lagom omfattning som motsvarar projektdelens storlek på 3 hp (runt 80 timmar per person).
Omfattningen innebär inte bara "kodvolym" (antal rader kod) utan beror mycket på komplexitet, variation, och så vidare. Ett projekt med stora mängder likformig kod har inte lika stor omfattning som det kan se ut vid första anblicken. Kod som lätt kan genereras automatiskt (getters, setters, equals-metoder) bidrar inte så mycket eftersom man lätt kan skapa tusentals rader sådan kod på några minuter med verktygen i IDEA. Kod som går vidare med samma grundstruktur som Tetris-labben får mycket "till skänks" i fråga om kodning och tankeverksamhet, och kan inte heller bidra i lika hög grad.
Dessutom är det viktigt att "smart är bättre än långt". Ineffektiv kod, t.ex. upprepningar av nästan identisk kod, har ofta lett till komplettering.
Så hur vet jag vad min omfattning är? Ja, det är alltså inte helt lätt att svara på utan en full granskning. Rent statistiskt kan vi säga att godkända projekt brukar ha minst 600-700 rader kod (exklusive tomrader, kommentarer osv), men det är bara statistik i efterhand – vi utgår inte från radantalet när vi bedömer omfattningen.
Rekommendation: Fokusera på kvalitet, funktionalitet och att utnyttja era 80(+80) timmar väl. Om du funderar över projektets omfattning, diskutera med en erfaren handledare i god tid.
-
Projektrapporten måste följa mallen, innehålla den information som vi har begärt, och uppfylla betygskraven för UML-diagram.
-
Vid inlämning ska du följa alla inlämningsinstruktioner. Annars kan din inlämning återlämnas utan granskning.
Specifika programmeringstips
Punkterna i förra avsnittet innehåller allmänna områden att tänka på. Vi har också en sida med många specifika programmeringstips och saker att tänka på i projektet. Där kan du få mer konkret vägledning.
Bedömningskriterier: Kodanalys
En hel del potentiella problem i programkod kan upptäckas automatiskt, genom algoritmer som analyserar koden. Vår automatiska kodanalys gör detta åt dig och skapar issues i ditt Gitlab-projekt. Detta ger omedelbar återkoppling och ger handledarna mer tid till icke-trivial vägledning. Så länge som analysen tas på allvar leder den också till färre kompletteringar (och tidigare CSN-pengar...) då kvaliteten höjs före inlämningen.
Kodanalysen visar problem som den tror finns i koden, men automatisk analys kan ibland ge "false positives". För att ge en vink om sannolikheten att det faktiskt finns ett problem visar vi för många varningar att de brukar vara korrekta ALWAYS, ALMOST_ALWAYS, USUALLY, eller SOMETIMES. Men avfärda inte varningen direkt bara för att den inte har maximal sannolikhet. Vi aktiverar bara varningar om de tillräckligt ofta indikerar faktiska problem som skulle kunna leda till problem i inläsningen.
Kodanalysen visar också hur "allvarligt" den tror att problemet är relativt varje betyg (3/G, 4, 5/VG): SHOWSTOPPER, SEVERE, WARNING, WEAKWARNING, POLISH.
Så vad ska man göra åt en varning... om man vill uppnå perfektion?
-
Undersök om problemet är ett riktigt problem eller en "false positive". Läs informationen om felet, och fråga handledaren vid behov. Se till att vara helt säker på din sak.
-
Om det är ett riktigt problem: Åtgärda det.
-
Annars: Skriv en kommentar vid raden där problemet indikeras, och ge en tydlig motivering till varför du anser att varningen är fel och varför koden inte alls bör ändras. Givetvis kan du hänvisa till längre förklaringar på annan plats, men den hänvisande kommentaren ska då finnas nära själva varningen.
Så vad ska man göra åt en varning... om man inte är perfektionist?
Vi kräver så klart inte total perfektion i inlämningarna. Istället:
-
Ju högre varningsnivå (SHOWSTOPPER / SEVERE / ...) relativt ett visst betyg, desto viktigare att åtgärda problemet eller att motivera varför det faktiskt inte finns något fel.
-
En SHOWSTOPPER som varken är åtgärdad eller korrekt motiverad gör att man inte alls kan få betyget, och leder normalt till komplettering (om varningen är SHOWSTOPPER för betyg 3). SEVERE innebär att det är ett allvarligt problem som kanske kan vägas upp av att resten av projektet håller hög kvalitet, men det kan vara bäst att inte chansa. Man kan oftast ha några WARNING utan att det är ett stort problem, och ett lite större antal WEAKWARNING. Vi ignorerar mer eller mindre POLISH, så länge det inte är enorma mängder, men vill ändå ge sådana påpekanden för att ni ska få en chans att lära er mer.
-
Både att ignorera en korrekt varning och att inte motivera en felaktig varning räknas alltså som "icke hanterade varningar". Att motivera varför varningen är felaktig ingår nämligen i examinationen och kan i princip ses som en tentafråga. När du tänker genom din motivering kan det också hända att du inser att du hade fel, och att varningen faktiskt var korrekt...
Vi får OFTA in inlämningar där alltför många problem är ignorerade. Gör det på egen risk.
Ju mer centralt ett problem är för kursens innehåll och mål, ju lättare det var att inse att problemet faktiskt existerade i koden, och ju lättare problemet är att fixa (i t.ex. IDEA), desto svårare blir det för oss att ha överseende med det och släppa genom inlämningen. Om kodanalysen uttryckligen har pekat ut ett viktigare problem finns det ingen tvekan om att du visste om problemet, och då är det svårare att godkänna inlämningen.
Vi kräver inte perfektionism men kan inte heller acceptera alltför stora mängder varningar.
I den inlämnade koden får du använda @SuppressWarnings
eller //noinspection
för
att undertrycka (suppress) inspektionsvarningar som du anser är felaktiga; se Suppress inspections.
Använd inte "disable inspections", då detta stänger av hela inspektionen så att du inte ser var du behöver
skriva motiveringar. Detta fungerar dock bara för varningar som kommer från IDEA, och (för tillfället) inte på
varningar som vi har implementerat i ett eget verktyg.
Detta ersätter inte behovet av motiverande kommentarer för att förklara varför en varning var ogiltig och skulle undertryckas!
Bedömningskriterier för programkod: Betyg 4
För betyg 4 krävs att man uppfyller kraven för betyg 3, samt högre kvalitet i allmänhet. Dessutom finns följande krav.
-
Första delen av labb 5, markerad med "Betyg 4", måste genomföras individuellt. Det går bra att bara en medlem i en projektgrupp gör detta (och då kan en eventuell partner få lägre betyg på det sammanlagda momentet i LADOK).
Död kod ska tas bort, det vill säga kod som aldrig kan anropas och därmed inte kan testas eller demonstreras ordentligt. Detta påpekas i kodanalysen. Små mängder död kod kan accepteras, medan större mängder kan leda till komplettering.
Varje klass ska kommenteras med en övergripande Javadoc-kommentar som beskriver klassen (syfte, användning, relation till andra klasser, ...). Kommentarerna ska vara tillräckligt informativa för att man ska kunna få en rimlig förståelse för klasserna helt utan att läsa någon programkod och får alltså inte vara alltför korta!
! Javadoc-formatet beskrivs i en kursbok du har valt, eller t.ex. i Oracles egen dokumentation. Självklart kan även andra kommentarer behövas.
Dessutom ska alla eventuella publika fält Javadoc-dokumenteras ordentligt. (Sådana fält ska normalt undvikas.)
Upprepad / repetitiv kod bedöms hårdare.
Genom att abstrahera, parameterisera och generalisera kan man på kortare tid skriva kortare, mer lättläst och mer utökningsbar kod utan onödiga upprepningar.
Alltför repetitiv och ineffektiv kod ger ofta komplettering, även när det inte gäller "exakt" upprepning. Gå genom all din kod och undersök om det finns något du tycker borde kunna uttryckas effektivare, kod där det känns som om du inte borde ha behövt skriva så mycket som du gjorde. Antagligen behövde du inte det!
Javas stöd för resurser ska användas om du behöver läsa in filer (bilder, ljud, banor, inställningar osv.) som tillhör och "levereras med" programmet. Använd alltså
ClassLoader.getSystemResource()
och använd inte vanlig filhantering. På det sättet undviker man att behöva ange var filerna finns i en specifik installation, och filerna kan hämtas även om hela programmet råkar vara packat i en JAR-fil (liknande ZIP-fil). Om du även skriver till en fil behöver du inte använda resurser för den filen, eftersom du i så fall ändå måste veta var filen är placerad.-
Med "upptäckta fel" menar vi dels undantag (exceptions) som fångas efter att de uppstår i egen kod eller andras kodbibliotek, dels andra typer av fel som man upptäcker på andra sätt, t.ex. genom att man själv kontrollerar om användaren ger felaktig input eller om en metod signalerar fel genom att returnera null.
Upptäckta fel ska hanteras korrekt. Detta innebär bland annat att fel ska hanteras på rätt plats, att man inte får "fånga och ignorera / glömma bort" felen, att man ska tänka på potentiella följdfel (om jag fångar felet här och fortsätter, vad händer då?), och att man vid behov ska ge rimliga felmeddelanden till användaren. Läs vidare i de specifika tipsen!
Om det är helt orimligt att programmet ska kunna fortsätta köra efter felet, är det acceptabelt att helt enkelt skriva ut en stacktrace och avsluta programmet. I övrigt ska fel hanteras enligt bästa förmåga.
Se även kraven på UML-diagram i rapporten.
Bedömningskriterier för programkod: Betyg VG/5
För betyg VG/5 krävs att man uppfyller kraven för betyg 4, samt högre kvalitet i allmänhet. Dessutom finns följande krav.
-
Motsvarande delar labb 5 (hela labben för betyg 5, nästan hela för VG) måste genomföras individuellt. Det går bra att bara en medlem i en projektgrupp gör detta (och då kan en eventuell partner få lägre betyg på det sammanlagda momentet i LADOK).
Upprepad / repetitiv kod bedöms ännu hårdare.
Genom att abstrahera, parameterisera och generalisera kan man på kortare tid skriva kortare, mer lättläst och mer utökningsbar kod utan onödiga upprepningar.
Alltför repetitiv och ineffektiv kod ger ofta komplettering, även när det inte gäller "exakt" upprepning. Gå genom all din kod och undersök om det finns något du tycker borde kunna uttryckas effektivare, kod där det känns som om du inte borde ha behövt skriva så mycket som du gjorde. Antagligen behövde du inte det!
-
Projektet ska använda sig av loggning med hjälp av Javas loggningssystem (
java.util.logging
). Loggning ska ske till en loggfil med hjälp av klassenFileHandler
.Detta inkluderar att eventuella exceptions som fångas ska loggas, tillsammans med rimliga felmeddelanden. Även i andra delar av projektet ska det finnas loggning av minst ett 10-tal rimliga (eller i alla fall "icke orimliga") händelser. Hitta själv på var detta ska ske.
Då detta bara gäller betyg 5/VG får man själv läsa på i dokumentationen för att lära sig hur loggning fungerar.
Att projektet alltid ska använda loggning, och inte bara om/när exceptions fångas, är nytt för 2022. -
För att testa vissa typer av fel i resurshantering ska projektet i förväg köras från en JAR-fil innan inlämning. Se instruktioner under betyg 4 ovan.
Se även kraven på UML-diagram i rapporten.
Bedömningskriterier för projektrapport
Den slutliga projektrapporten skrivs i andra halvan av den mall vi har tillhandahållit (och den inledande projektplanen behålls i inlämningen). Mallen ska så klart användas och ska innehålla all den information som vi har begärt genom mallens instruktioner.
Projektrapportens implementationsavsnitt måste ge en bra översikt över programmet, typiskt på 3–6 sidor (givet att det mesta är text). Detta är en del av examinationen som delvis ersätter en tenta.
Projektrapportens kvalitet inverkar också till viss del på bedömningen av projektet – har ni gjort ett bra jobb med att beskriva implementationen? Det mesta av detta går som vanligt inte att kvantifiera: Går det att förstå hur implementationen fungerar? Går det att förstå strukturen? En aspekt kan vi dock ge siffror på:
För betyg 3/G ska man ha minst 1 UML-diagram i implementationsbeskrivningen i rapporten.
Betyg 4: Minst 2 diagram
Betyg VG (filfak): Minst 3 diagram
Betyg 5: Minst 4 diagram
Dessa diagram ska då användas på ett rimligt sätt för att illustrera olika aspekter av ert projekt. Det betyder att man inte tar med ett gigantiskt klassdiagram som visar ärvningsrelationer mellan alla klasser i hela projektet. Istället går man från andra hållet: När man vill beskriva en specifik aspekt av implementationen, t.ex. en viss hierarki av klasser och gränssnitt som man har skapat, skapar man också ett UML-diagram som gör det lättare att förstå det man har beskrivit.
Klassdiagram som visar hierarkier är bara en av flera möjligheter. Man kan också använda UML för att visa t.ex. komposition (objekt av typ X "har" objekt av typ Y) och mycket annat.
UML-diagram kan med fördel skapas i IDEA (ultimate edition, som finns på universitetet / kan användas med studentlicens) och klistras in i dokumentet. Man kan välja att börja med ett tomt diagram och manuellt välja vilka klasser som tas med (tryck SPACE), eller att börja med ett större diagram och ta bort det som inte önskas (högerklick, "delete").
Sidansvarig: Jonas Kvarnström
Senast uppdaterad: 2022-02-06