Göm menyn

Inlämning av projektkod och dokumentation

Allmänna regler

Vi har ganska strikta instruktioner för inlämning. Vi har många inlämningar, så om handledare skulle lägga ner 5-10 minuter "i onödan" per inlämning blir det snabbt till många timmar som kunde ha lagts på handledning och kursutveckling. Därför måste vi returnera inlämningar som inte följer instruktionerna för komplettering.

Detta gäller också att hantera de problem som upptäcks av automatisk kodanalys, vilket diskuteras mer längre ner på sidan.

Inlämningsprocedur

Inlämningen går till så här:

  1. Läs reglerna om klassbibliotek, lånad kod och samarbete så att du inte riskerar misstanke om fusk / plagiat / vilseledande!
  2. Se till att du har demonstrerat. Handledaren kan ha kommentarer redan vid demo, så du ska demonstrera före inlämning (och före deadline). Demonstrationer sker på distans, via Teams.

  3. Är detta en komplettering eller plussning? Beskriv i så fall i filen "kompletteringar.txt", i rotkatalogen för projektet, hur varje enskild kommentar från handledaren har hanterats: Vad som ändrats och var i koden, hur du har löst problemet, och annan information som är relevant för att handledaren lätt ska se vad som gjorts.

    Gör du flera kompletteringar ska gamla kommentarer vara kvar och tydligt skilda från nya kommentarer (markera med kompletteringsdatum). Detta underlättar för oss och är en del av examinationen där du visar att du förstår varför kompletteringen behövdes.

    Se till att filen är adderad till Git, i projektets rotkatalog, och incheckad. Kodanalysen bör upptäcka om något är fel.

  4. Checka in all kod och dokumentation, inklusive den fullständiga projektrapporten, och pusha till det Git-repo du har fått på LiU:s Gitlab. Ja, det måste vara det repo som vi har skapat när du anmälde dig i Webreg. Det är detta som vi kan hantera i vårt inlämningssystem eftersom vi då har möjlighet att använda webhooks och annan funktionalitet.

    Alla incheckade och pushade filer kan ses direkt i Gitlabs webgränssnitt. Icke incheckade filer kan ses i IDEA (Tool window "Git", fliken "Local Changes", sedan "Unversioned Files") eller via git status på kommandoraden.

    Överkurs: Om du använder externa klassbibliotek ska även dessa finnas med och vara konfigurerade korrekt i IDEA – våra system använder inte verktyg som Maven etc. för att hämta dem. (Om något saknas ska det synas i kodanalysen.)

  5. Gå noga genom varningarna från den senaste utökade kodinspektionen som du får som issues i Gitlab. Ser du något mer du vill åtgärda innan inlämning? Gör det, och titta sedan på nästa kodinspektion för säkerhets skull!

    Det här är till stor del ett sätt att lära sig skriva kod som inte bara gör vad den ska utan även är välskriven och strukturerad. Tänk alltså inte att "jag borde ha kunnat det här", utan se verktyget som en del av studiematerialet! Prova en lösning, och få nya uppslag och ny kunskap via analysen av den lösningen.

    Du behöver tänka på:

    • Om kodanalysen visar stora röd-rosa rutor med fatala fel, t.ex. att du har flera IDEA-projekt konfigurerade eller att det finns syntaxfel, ska du inte lämna in. Inlämningen är felaktig och kommer inte alls att granskas. Prata med en handledare i god tid om du behöver hjälp.

    • Vissa indikationer kan vara "false positives". Analysen är alltså inte ofelbar utan kan signalera ett möjligt fel som i själva verket inte finns där. Vi försöker indikera hur ofta vi väntar oss att det händer genom att markera att en indikation stämmer "always", "almost always", "usually" eller "sometimes", men i vissa fall finns ingen sådan markering eftersom vi inte har tillräcklig statistik.

      Om du anser att en indikation är "falsk": Tänk efter en gång till och läs informationen noga, och prata gärna med handledaren om du är särskilt osäker. Tycker du fortfarande att indikationen är falsk bör du skriva en kommentar om detta, särskilt om det inte är helt uppenbart varför den är falsk.

    • Vi gör också en uppskattning av hur allvarlig en viss typ av indikation brukar vara. Här väger vi också in hur mycket jobb det är att bli av med indikationen, så ett mindre allvarligt problem kan hamna högt i skalan om det är väldigt enkelt att fixa. Detta är alltså en uppskattning och den slutliga bedömningen måste göras av en människa.

    Ignorera inte den utökade kodanalysen! Det som visas där är oftast sådant som granskaren ändå skulle ha kommenterat på. Nu får du chansen att få de kommentarerna redan innan inlämningen så du kan polera koden och få bättre chans till godkänt / högre betyg redan från början.

    Vi kräver inte perfekt kod, men ju allvarligare en indikation är, desto viktigare är det att jobba vidare med den. Det räcker normalt med en enda SHOWSTOPPER för att få komplettering. SEVERE kommer därefter i "viktighet", och sedan WARNING och WEAKWARN. Är något markerat POLISH ser vi det snarare som "bra att veta" och "trevligt om det skulle fixas" men det hindrar inte att man får godkännande eller ett visst betyg om det inte finns i extremt stora mängder.

    Vi släpper inte heller genom vad som helst. Det är inte helt ovanligt att vi får in projekt (och i vissa fall labbar) som ger omedelbar komplettering på grund av större mängder problem som redan har pekats ut i analysen. Finns det alltför många sådana problem är det ett slöseri med den begränsade handledningstiden att handledaren går genom allt på djupet, och då pekar vi istället ut olika delar av den färdiga analysen.

    Det slutliga avgörandet ligger hos examinatorn och sker efter inlämningen. Precis som på en tenta kan man aldrig veta exakt i förväg vilket betyg man kommer att få: Man gör så gott man kan, och sedan lämnar man in. Man kan inte heller veta exakt "när det räcker": Man läser på inför tentan till man tror att man kan tillräckligt, och man arbetar vidare med labben eller projektet till man tror att koden är tillräckligt bra. Analysen ger en god hjälp på vägen men ingen kan avgöra något i förväg.

  6. Tänk extra noga på följande punkter, som ofta har gett komplettering under tidigare år:

    • Är koden lättläst och lättförståelig? Har du satt bra namn på klasser, metoder, fält och variabler, som en "utomstående" kan förstå? Har du brutit ut deluttryck till egna namngivna variabler för att förklara vad mindre uppenbara delar av ett uttryck egentligen betyder?

    • Har du använt våra tips för att undvika duplicerad, ineffektiv kod? Har du hittat gemensamma mönster där man t.ex. kan bryta ut hjälpmetoder som minskar upprepningen även där koden inte är identisk?

    • Har du testat din felhantering? Vi har föreslagit att själv "skapa" fel genom att köra throw new FooException(); inuti try på varje plats där man gör catch (FooException e), så att man ser vad som händer när ett fel faktiskt uppstår även om det felet aldrig uppstod vid en "vanlig" körning.

  7. Skapa en tagg (etikett) i Gitlab enligt instruktionerna nedan. Detta visar oss vilken version av koden som lämnades in vid inlämningsdatumet.

    Överkurs

    Skapar du en tagg på annat sätt, t.ex. på kommandoraden, måste du se till att explicit pusha den till Gitlab: git push origin [tagnamn]! eller git push origin --tags! En vanlig "push" skickar inte över taggar.

    1. Logga in på gitlab.

    2. Gå till ditt projekt och välj "tags".

    3. Välj "New tag".

    4. Du kan gärna sätta taggnamnet till "t1" om detta är första gången du lämnar in. Om du får komplettering kan du nästa gång sätta en ny tagg "t2", och så vidare. Exakt vad taggarna heter och vilka nummer de har är egentligen mindre viktigt, men det är bra om det syns på något sätt i vilken ordning de kommer (så att "t2" inte är en nyare tagg än "t4", eller taggarna heter "x", "4" och "nej", till exempel).

      Flytta aldrig en tagg så den pekar på en annan commit! Varje gång du taggar en version skapas en kodanalys för den versionen. Flyttar du taggen uppdateras inte kodanalysen i och med att den redan existerar för det taggnamnet. (Vet du inte vad vi pratar om? Då är det ingen fara.)

      Med andra ord: Om du skapar en tagg och sedan inte vill lämna in den taggade versionen, skapar du en ny tagg för det du vill lämna in och låter den gamla ligga kvar "oanvänd".

    5. Låt "Create from" vara kvar på "master" (under förutsättning att ni inte har valt att lägga den slutliga versionen i någon annan gren...).

    6. Meddelanden och "release notes" behövs inte.

    7. "Create Tag"!

  8. Läs genom betygskriterierna en gång till och se till att koden uppfyller grundkraven, inklusive krav på eventuell felhantering, resurshantering med mera. Gå gärna genom de specifika tipsen.

  9. Dubbelkolla att projektdokumentet är uppdaterat. Följande instruktioner gäller både förstagångsinlämningar, kompletteringar och plussningar.

    I den första delen, projektplanen, behöver man främst uppdatera sådana delar som vi kan ha nytta av för att förstå slutresultatet. Man behöver alltså inte uppdatera t.ex. milstolpar om de har ändrats efter att man gjorde sin ursprungliga plan, eftersom de främst skulle vara till hjälp med er egen planering. Däremot kan man behöva ändra bakgrundsinformationen om man har ändrat inriktning på projektet. Det du uppdaterar kan ersätta den gamla planen, eller kan läggas i en separat underrubrik efter originalplanen.

    Den andra delen av dokumentet, projektrapporten, behöver helt och hållet stämma överens med det slutliga projektet. Det gäller även vid kompletteringar.

    Dokumentet ska använda den korrekta mallen och ska innehålla all den information vi efterfrågar med korrekt numrering av avsnitt. Se det som en tenta – en viktig del av betyget!

    Se till att dokumentet är exporterat till PDF-format. Använd t.ex. File | Export to PDF i OpenOffice Writer. Döp beskrivningen enligt följande mönster, utan mellanslag i filnamnet. ID måste alltså finnas med.

    • liuid123-rapport.pdf om du arbetar ensam
    • liuid123-liuid456-rapport.pdf om ni arbetar i par

    Se till att rapporten och den exporterade PDF-filen är adderade till Git, i roten av projektet, och incheckade med korrekt namn. Den utökade kodanalys som ni får i era issues ger ett felmeddelande om detta inte stämmer (givet att ni använder det Gitlab-projekt vi har skapat åt er för just projektet).

    Det går utmärkt att skriva på svenska. Alla handledare förstår svenska tillräckligt bra för att läsa dokumentationen.

  10. Dubbelkolla att eventuell lånad kod är markerad enligt instruktionerna. Den utökade kodanalys som ni får i era issues visar korrekt markerad lånad kod med en annan bakgrundsfärg. Om koden är lånad men inte tydligt markerad kan det leda till misstanke om fusk.

  11. Projektet måste lämnas in i IDEA-format. Detta är redan fixat i de ursprungliga projekten ni får på Gitlab och utan detta fungerar inte den automatiska kodanalysen. De filer vi kommer att se är de som syns i HTML-sidan med kodanalys.

  12. Dubbelkolla och trippelkolla att allt är korrekt. Inlämningar som har okommenterade varningar, saknar nödvändiga filer eller uppenbart bryter mot viktiga regler kommer att returneras utan bedömning.

  13. I stället för att lämna in programkod och dokumentation via epost till assistenterna hanterar vi detta via issues i ett centralt Gitlab-repo.

    Detta är ett centralt repo som vi länkar till nedan. Du kan inte lägga det som en issue i ditt eget repo; det är som att skicka epost till dig själv. Använd länken nedan efter att du har läst instruktionerna. En issue ska skapas innan deadline.

    Detta ser ut ungefär så här:

    Om ingen text är ifylld i rutan är du på fel plats. Om det inte står "java-project-handins" högst upp är du på fel plats.

    Det enda du behöver fylla i här är titel och en länk till din tagg i Gitlab. Du hittar denna länk genom att leta upp taggen i ditt projekt i Gitlab, under Repository / Tags. Klicka på taggnamnet och kopiera länken – exempelvis https://gitlab.liu.se/tddd78-2048/tddd78-projekt-2048-u1-g24-99/-/tags/t5.

    Från detta hittar vi automatiskt om det är projekt eller labbar som lämnas in, vem som lämnar in, och givetvis även vilken tagg det gäller. Vi kommer att automatiskt göra din issue konfidentiell.

    Då ska det se ut ungefär så här:

    Det är OK att fylla i mer information om inlämningen om det är något du vill tala om för oss.

    Ändra aldrig på en issue när du väl har skickat in den! Då kan den redan ha börjat behandlas av systemet och granskaren kanske inte ser dina ändringar, t.ex. om du ändrar länken till att peka på en annan tagg. Stäng i så fall din issue och öppna en ny istället.

Labb av Jonas Kvarnström, Mikael Nilsson 2014–2021.


Sidansvarig: Jonas Kvarnström
Senast uppdaterad: 2021-06-08