Individuell P-uppgift

Läs igenom hela dokumentet innan du börjar, eftersom senare detaljer är viktiga för tidigare steg.

P-uppgiften är ett mindre programmeringsprojekt på 100-500 rader kod (det är inte ett krav, men ett ungefärligt mått på vad som är rimligt). Uppgiften är individuell.

Välj en uppgift från listan över P-uppgifter. Föredrar du att hitta på en egen uppgift, fråga först kursledaren om den är rimligt svår och omfattande.

Projektet behöver födas och växa upp på Git under kursens gång. Single commit push godkänns inte. Det behöver finnas en commit-historik för hur ditt individuella projekt blev till. Använd det genererade repot gruprog[årets omgång]/[ditt användarnamn]-p-uppgift på https://gits-15.sys.kth.se.

Specifikation

Innan du ger dig i kast med att programmera ett större projekt så behöver du skriva en liten specifikation och få den godkänd av en labbassistent.

Specen ska vara en pdf-fil eller i Markdown Links to an external site.-format och ligga på Git. 1-2 sidor är lagom mycket för en spec i den här kursen. Här finns en exempelspecifikation.

Specen ska bestå av fyra delar som visar att du har en plan inför P-uppgiften.

  1. Inledning: Introducera projektet eventuellt med Wikipedia-länkar för att förklara bakgrund eller liknande projekt. Beskriv uppgiftens utmaningar och svårigheter. Fokusera på vad som kan tänkas ta mycket tid att programmera. Motivera varför någonting är svårt.
  2. Användarscenarier: Skriv minst två väsentligen olika berättelser om hur en användare kan tänkas använda programmet när det är klart. Beskriv användarens interaktion med programmets gränssnitt och hens tankar kring vad som händer. I användarscenarierna så är vi inte intresserade av program- och dataflöde. Det är en senare punkt.
  3. Programskelett: Skriv en skiss över koden i din P-uppgift med dina funktioner, klasser och metoder. Skriv klassens/metodens/funktionens huvud följt av sin dokumentationskommentar. Dokumentera parametrarnas syfte och funktionernas/metodernas eventuella returvärden. Om du har en klass, se till att det framgår om den motsvarar ett enstaka objekt av någonting i programmet eller om den ansvarar för en lista av sådana objekt. Om du har en funktion eller metod, se till att (eventuella) parametrar och returvärden är beskrivna.
  4. Minnet: Förklara hur datan skapas, organiseras och uppdateras i datorns minne. Hur organiseras objekt av din klass i datorns minne? Rita en partiell minnesbild, dvs vi är inte intresserade av alla detalker om hur objekten ligger i minnet som på kontrollskrivningen utan de mest väsentliga delarna.
    Överkurs för del 4: Rita eventuella bilder som UML-diagram.

Specifikationen redovisas separat och det rekommenderas att göra den tidigt för att få en assistents återkoppling på dina idéer.

Specifikationen är bra att få klart tidigt i kursen. För betygskravet på när specen ska vara klar, se kursöversikt i vänstermarginalen.

Överkurs: Rekommenderad överkurs är att använda Git fullt ut med milestones Links to an external site.. Det är dock inte ett betygskrav.
Överkurs för webbapplikationer: Se till att ditt kan deployas i Docker-containers som sköts av Kubernetes. Använd Github Actions för att implementera CI/CD (Continuous Integration/Continuous Deployment).
Överkurs för lokala applikationer: Gör paketering och installationsscript för att andra ska kunna installera projektet på sin dator.

Programmeringen

Förutom det som står i lydelsen för din P-uppgift ska varje program innan redovisning uppfylla följande 9 krav:

  1. Klasser: Koden behöver använda minst en klass på en central plats för att lösa uppgiften. Klassen/klasserna behöver ha en init-metod. Om du har svårt att se ett sätt att dela in uppgiften i klasser så rekommenderas mönstret model-view-controller Links to an external site..
  2. Struktur: Koden ska vara indelad klasser, metoder och funktioner. Det är ok att ha konstanter och ett anrop till main globalt. Resten av koden ska ligga i klasser och funktioner.
  3. Funktionerna, klasserna och metoderna ska vara lagom stora. Lägg till exempel inte större delen av koden i en mainmetod och ha inte ett fåtal funktioner vars innehåll är one-liners som anropas en gång. Ha inte heller all kod i en jätteklass.
  4. Varje klass, metod och funktion ska vara dokumenterad med minst en välformulerad mening. Kommentarer ska förklara funktionens/klassens interface. De ska inte vara en rad-för-rad-översättning från Python till ett mänskligt språk. Undantag ges för rena get- och set-metoder, dvs de som endast sätter och läser privata fält.
  5. Använd lokala variabler för delresultat i en funktion. Undvik globala variabler. Globala konstanter är däremot ok. Det är också OK att initialisera konstanter av typen debug_flag, logging_level i en init-metod först i programmet som därefter är konstanter under programmets körning.
  6. Undvik onödig kodupprepning Links to an external site.. Använd inte copy paste för en del av koden som borde ligga i en funktion istället. Stapla inte mängder med if-satser för något som borde ha en for-loop och använd inte en for-loop för något som borde ha ett matematiskt uttryck (till exempel en aritmetisk summa).
  7. Undvik hårdkodning och programmera istället kod som går att återanvända och utvidga. Om du har en bank så ska den kunna hantera godtyckligt antal kunder och inte hårdkoda tre kunder.
  8. Utskrifterna eller användargränssnitten ska vara lätta att förstå. Användarna ska inte behöva se loggar från programmet eller tekniska felmeddelanden.
  9. Dina namn på variabler, funktioner, metoder och klasser ska vara beskrivande och lättbegripliga. Använd gärna x, y och z om det är koordinater i rymden, men välj hellre friction_coefficient, downward_force eller cube_mass om det bättre beskriver vad din variabel representerar.

Om din kod får 4 eller fler oåtgärdade påpekanden enligt ovanstående lista så blir den inte godkänd.

Om din kod får 2-3 oåtgärdade påpekanden enligt ovanstående lista kan du som bäst få betyg E på P-uppgiften oavsett vilket betyg uppgiften var på.

Om din kod har 1 oåtgärdat påpekande enligt ovanstående så kan du som bäst få betyg D på P-uppgiften oavsett vilket betyg uppgiften var på.

Om du inte uppnår kraven för det betyg som du siktar på så kan assistenten säga något i stil med "Jag kan godkänna dig nu med ett D men om du vill ha C så måste du åtgärda dessa punkter." Då behöver dessa åtgärdas innan deadline för det högre betyget, vilket är samma som P-uppgiftens deadline.
Peer Review - Kamratgranskning

När du är klar med uppgiften behöver du hitta en annan person på kursen och granska koden enligt ovanstående 9 punkter. Skriv ett kort protokoll (c:a 1/2 - 1 skärmsida) med de fetstilsmarkerade orden och uttrycken enligt ovan som rubriker. Skriv varför du tycker att koden uppfyller eller inte uppfyller kravet. När det blir dags att redovisa behöver ni båda vara med och granskaren ska presentera uppgiften. Programmeraren till koden ska försvara koden och slutligen ska både granskaren och programmeraren vara beredda på frågor från assistenten.

Den granskade programmeraren får uppdatera sin kod inför slutredovisningen efter att ha läst kodgranskningen, men berätta det i så fall för assistenten under granskningsredovisningen så att vi inte tycker att kodgranskaren har varit för orättvis mot er kod.

Slutredovisning

När ni är redo för slutredovisning, se till att er granskning av en annan student ligger i repot för p-uppgiften. Se också till att skriva i issuet vem som har granskat, helst med en länk till granskarens githubrepo, men annars åtminstone användarnamn.
Projektet avslutas med en redovisning där du som skrivit uppgiften och din granskare tillsammans tar er till ett labbpass och sätter upp en av er på kön.

1. Granskaren och författaren till koden är beredda på att visa legitimation.
2. Granskaren presenterar programmet och resultatet av kodgranskningen. (ungefär 1-2 minuter).
3. Författaren till koden försvarar sitt program och reder ut missförstånden.
4. Lärarassistenten ställer frågor till granskaren och författaren och om alla svar är rimliga så får redovisningen och granskningen godkänt. Om granskning eller projekt har allvarliga brister så får den delen inte godkänt. Assistentens bedömning gäller här.
5. Projektet behöver ligga på Git i ett privat repository. Använd det du fick i kursens början, dvs [användarnamn]-p-uppgift.

Deadline

Om uppgiften som helhet inte är klar sista labbtillfället på kursen (se kursöversikt för när det är) så kan du som bäst få betyg E på kursen. När du är redo att redovisa något delmoment eller uppgiften som helhet: Skapa ett issue på Git med ämnet "Redovisning". En assistent kommer att rätta din labb och boka tid för redovisning med dig.

Betyg

Om en uppgift har flera betygsnivåer så behöver samtliga under det betyg du siktar på också vara uppfyllda. Om du exempelvis gör ett grafiskt användargränssnitt på en uppgift som har lägre betygsnivåer (E-C) så behöver de lägre betygsnivåerna också vara uppfyllda vid redovisningen.

För betyg A krävs ett grafiskt användargränssnitt. Det behöver vara strukturerat (inte bara knappar och paneler huller om buller utan indelat med någon form av layoutmanager så att knapparna finns på ett ställe och visualiseringar någon annanstans), men det behöver inte vara vackert eller intuitivt. Ni behöver inte rita ikoner för knapparna utan det räcker med textfält. Om det finns ett GUI så är det inte OK att kräva att användaren ska använda terminalen för sådant som är rimligt att ha en knapp för.