⚠️ Viikon tehtävien palautuksen deadline on tiistai 26.11. klo 23:59. Tehtävät on tarkoitus tehdä joko pajassa tai omatoimisesti.

Tehtävät palautetaan GitHubin avulla Labtooliin rekisteröimääsi repositorioon. Muista pushata tehtävät GitHubiin ennen palautuksen deadlinea! Klo 00 jälkeen tulevia repositorion päivityksiä ei huomioida pisteytyksessä, eli ne tuovat 0 pistettä.

Palautuksesta saadut pisteet ja palaute löytyy Labtoolista viimeistään deadlinea vastaavan viikon loppuun mennessä. Muista tarkistaa saamasi pisteet ja palaute. Jos pisteytyksestä herää kysymyksiä, lähetä viesti Labtoolin kautta.

Tämän viikon harjoitustyön palautuksesta on tarjolla 3 pistettä.

Pylint ja koodin laadun staattinen analyysi

Koodin testauksen lisäksi koodin laadun ylläpitäminen on tärkeää. Laadun ylläpitäminen on mahdollista erilaisilla manuaalisilla menetelmillä, kuten laatuvaatimusten dokumentoinnilla ja koodikatselmoinneilla. Monet manuaaliset laadunhallinnan menetelmät osoittautuvat kuitenkin laajoissa ohjelmistoprojekteissa usein turhan aikaavieviksi ja virhealttiiksi. Staattinen analyysi on menetelmä, jonka avulla koodia voidaan analysoida automatisoidusti ilman, että sitä tarvitsee suorittaa. Staattista analyysia hyödynnetään ohjelmistokehityksessä laajasti mm. ohjelmointivirheiden huomaamiseen ja laatutarkistuksien tekemiseen. Eräs Python-koodin staattisessa analyysissä laajasti käytetty työkalu on pylint. Pylintin avulla voimme määrittää koodin laadulle erilaisia vaatimuksia ja automatisoidusti tarkastaa, noudattaako tarkastettava koodi näitä sääntöjä.

Pylint is a tool that checks for errors in Python code, tries to enforce a coding standard and looks for code smells. It can also look for certain type errors, it can recommend suggestions about how particular blocks can be refactored and can offer you details about the code’s complexity.

Pylintin käyttöönotto projektissa

Pylint on helppo ottaa käyttöön Poetry-projektissa. Aloitetaan asentamalla pylint projektimme kehityksen aikaiseksi riippuvuudeksi:

poetry add pylint --group dev

Pylintille tulee määritellä joukko tarkistettavia sääntöjä. Säännöt määritellään projektin juurihakemiston .pylintrc-tiedostossa. Luo kyseinen tiedosto ja kopioi sinne tämän tiedoston sisältö. Tiedosto sisältää hieman muunnellun version pylintin suosittelemasta konfiguraatiosta, jota voi katsella komennolla pylint --generate-rcfile.

Pylintin laatutarkistukset voi suorittaa komentoriviltä siirtymällä ensin virtuaaliympäristöön komennolla poetry shell ja sen jälkeen suorittamalla komennon pylint src. Komento tulee suorittaa projektin juurihakemistossa, eli samassa hakemistossa missä pyproject.toml-tiedosto sijaitsee. Kyseinen komento suorittaa laatutarkistukset src-hakemistossa. Pylint antaa koodille “arvosanan” sen laadun mukaan, joka löytyy tulosteen lopusta:

Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

Laatutarkistuksien kytkeminen pois päältä

Lähtökohtaisesti pylintin huomauttamat laatuvirheet kannattaa yrittää kaikin keinoin korjata. Tämä johtaa lähes aina laadukkaampaan koodiin. Joissain tilanteissa voimme kuitenkin hyväksyä laatuvirheet ja kytkeä tarkastukset pois päältä. Tähän löytyy erilaisia keinoja.

Otetaan esimerkiksi seuraava src/index.py-tiedosto:

x = 3
print(x)

Komennon pylint src suorittaminen paljastaa, että pylint löytää tiedostosta seuraavan virheen:

src/index.py:1:0: C0103: Constant name "x" doesn't conform to UPPER_CASE naming style (invalid-name)

Eli tiedoston src/index.py-riviltä yksi löytyy väärin nimetty muuttuja. Rikottavan säännön nimi on tässä tilanteessa invalid-name. Järkevintä olisi vain antaa muuttujalle nimeksi X, mutta havainnollistetaan, kuinka säännön tarkistuksen voi ottaa riviltä pois päältä. Lisätään riville seuraava kommentti:

x = 3 # pylint: disable=invalid-name
print(x)

Nyt pylint src-komennon suorittaminen pitäisi kertoa, ettei virheitä enää löydy.

Voimme myös jättää tarkistuksien ulkopuolelle kokonaisia hakemistoja ja tiedostoja. Muokkaamalla tätä riviä .pylintrc-tiedostossa, voimme esimerkiksi jättää käyttöliittymästä vastaavan koodin hakemistossa src/ui ja testit hakemistossa src/tests tarkistuksien ulkopuolelle:

ignore=CVS,ui,tests

Älä jätä tarkistamatta mitään muuta kuin käyttöliittymään tai testeihin liittyvää koodia!

Korjaa ohjelmastasi kaikki pylintin ilmoittamat virheet. Vain harvoissa poikkeustilanteissa säännön kytkeminen pois päältä kommentin avulla on hyvä ratkaisu.

Integrointi editoriin

Monissa editoreissa on lisäosia, jotka huomauttavat laatuvirheistä suoraan koodissa. Tämä tekee niiden huomaamisesta ja korjaamisesta nopeampaa. Jos käytössäsi on Visual Studio Code, riittää että varmistat, että Python lisäosa on asennettu:

Visual Studio Code Python lisäosa

Tämän jälkeen Visual Studio Coden tulisi huomauttaa laatuvirheistä suoraan koodissa punaisella alleviivauksella. Viemällä hiiren ongelmallisen koodin päälle pitäisi aueta tarkempaa tietoa virheestä:

Visual Studio Code pylint

Jos integroinnin kanssa ilmenee ongelmia, tutustu Visual Studio Coden ohjeisiin.

Automaattinen formatointi

Tiettyjen laatukorjausten, kuten sisennysten ja liian pitkien koodirivien korjaaminen, tuottaa välillä turhaa manuaalista työtä. Koodin automaattisessa formatoinnissa auttaa autopep8-kirjasto. Kirjasto formatoi koodin automaattisesti PEP 8-tyyliohjeiden mukaisesti. Aloitetaan sen käyttö asentamalla se projektin riippuvuudeksi:

poetry add autopep8 --group dev

Tämän jälkeen voimme virtuaaliympäristössä formatoida src-hakemiston koodin komennolla:

autopep8 --in-place --recursive src

Komennolle voi myös tehdä oman tehtävänsä, jolloin suoritus onnistuu esimerkiksi komennolla poetry run invoke format.

Koodin formatointi onnistuu myös monissa editoreissa kätevästi yhdellä näppäinkomennolla. Ohje koodin formatointiin Visual Studio Codessa löytyy täältä.

Ratkaisuja yleisiin ongelmiin

  • Jos pylint ilmoittaa virheestä pygame has no X member, ongelman saa korjattua etsimällä .pylintrc-tiedostosta rivin extension-pkg-whitelist ja muokkaamalla sen muotoon extension-pkg-whitelist=pygame

Harjoitustyö

Tämän viikon aikana harjoitustyöhön toteutetaan uutta toiminnallisuutta, parannetaan sen dokumentaatiota ja kiinnitetään tarkempi huomio koodin laatuun.

Tämän viikon harjoitustyön palautuksesta on tarjolla 3 pistettä. Viikkopisteiden lisäksi kannattaa pitää mielessä harjoitustyön lopullisen palautuksen arvosteluperusteet.

Harjoitustyö 1: Uutta toiminnallisuutta

Kasvata ohjelmaa edellisestä viikosta (0.75p):

  • Ohjelman pystyy suorittamaan komentoriviltä komennolla poetry run invoke start
  • Suoritettava versio on kasvanut edellisestä viikosta ja toteuttaa edellisen viikon versiota suuremman osan määrittelydokumentin toiminnallisuuksista eli ohjelmaan on lisätty jotain käyttäjälle näkyvää hyödyllistä toiminnallisuutta
  • Merkitse lisäksi tarkastusta varten määrittelydokumenttiin valmiit toiminnallisuudet “tehty” merkinnällä

Ohjeita toteutukseen löydät täältä.

Harjoitustyö 2: Testaaminen

Edistä ohjelman testaamista (0.5p):

  • Sovellukselle tulee pystyä generoimaan testikattavuusraportti komennolla poetry run invoke coverage-report
  • Projektin juurihakemistossa tulee olla .coveragerc-tiedosto, jossa määritellään, mistä hakemistosta testikattavuus kerätään. Käyttöliittymään ja testeihin liittyvä koodi jätetään testikattavuusraportin ulkopuolle
  • Projektin src-hakemiston alahakemistoissa tulee olla tyhjät __init__.py-tiedostot ohjeiden mukaisesti, jotta kaikki halutut tiedostot sisällytetään testikattavuusraporttiin
  • Ohjelman testien haarautumakattavuuden tulee olla vähintään 20%
  • Testien tulee olla mielekkäitä, eli niiden on testattava jotain ohjelman kannalta merkityksellistä asiaa

Harjoitustyö 3: Koodin laatu

Kiinnitä koodin laadussa huomio seuraaviin seikkoihin (1p):

  • Sovelluslogiikka on riittävissä määrin eriytetty käyttöliittymästä
  • Ohjelman rakenne heijastaa ohjelman loogista rakennetta ja on nimennältään järkevä
  • Pylint on otettu käyttöön
    • Käytössä on tämä .pylintrc-tiedosto
    • Täydet pisteet saa, jos pylint-virheitä on alle 10
    • Käyttöliittymään tai testeihin liittyvän koodin voi jättää pylint-tarkistuksien ulkopuolelle
    • pylint: disable-kommenttien käyttö on kiellettyä ilman erittäin perusteltua syytä
  • Pylint-tarkistuksien suorittamista varten on toteutettu Invoke-tehtävä, jonka voi suorittaa komennolla poetry run invoke lint

Harjoitustyö 4: Dokumentaatio

Laadi ohjelman alustava rakenne luokka- tai pakkauskaaviona (0.75p):

  • Kaavion ei tarvitse merkitä kuin sovelluslogiikan kannalta oleelliset luokat
  • Voit tarvittaessa tehdä kaavion, josta ilmenee myös sovelluksen pakkausrakenne
  • Mallia voi ottaa referenssisovelluksesta
  • Lisää repositorion dokumentaatio-hakemistoon tiedosto arkkitehtuuri.md ja upota kuva tiedostoon. Tiedoston sisältö voi olla muilta osin tyhjä
  • Tiedostoon arkkitehtuuri.md tulee olla linkki repositorion README.md-tiedostosta referenssisovelluksen tavoin

Harjoitustyö 5: Changelog

Dokumentoi viikon aikana sovellukseen tehdyt merkittävät muutokset edellisen viikon tapaan dokumentaatio-hakemiston changelog.md-tiedostoon. Mallia voi ottaa referenssisovelluksesta.

HUOM: Changelog-merkinnän puuttuminen johtaa merkittävään pistevähennykseen.

Harjoitustyö 6: Pistevähennykset

Seuraavien kohtien puutteet vähentävät pisteitä:

  • Tuntikirjanpito on ajantasalla
    • Tuntien summan tulee olla merkittynä
    • Tuntikirjanpitoon ei merkitä laskareihin käytettyä aikaa
  • Viikolle on tehty changelog-merkintä changelog.md-tiedostoon
  • Repositorion README.md-tiedosto kunnossa
    • Tiedosto on kurssin tämän vaiheen osalta relevantin sisällön suhteen samankaltainen kuin referenssisovelluksen README.md
    • Kaikki ylimääräinen, mm. linkit laskareihin on poistettu
  • Repositorio siisti
    • Ei ylimääräistä tavaraa (mm. pytest- ja coverage-komentojen generoimia tiedostoja)
    • Laskarit jätetään hakemiston laskarit alle
    • Järkevä .gitignore-tiedosto olemassa

Ylimääräinen koodikatselmointi

Kurssin kuudennen viikon ohjelmassa on koodikatselmointi, jonka ohjeet löytyvät täältä. Tarkoituksena on, että itse kukin antaa palautetta jonkun toisen työstä. Katselmointi voi olla hyvin hyödyllistä niin katselmoitavan koodin kirjoittajalle kuin katselmoijallekin. Siksi voit niin halutessasi tehdä sitä jo viikoilla 4 ja 5 mikäli joku toinen osallistuja antaa harjoitustyönsä katselmoitavaksi. Tämä on täysin vapaaehtoista ja ylimääräistä, mutta voit saada tästä katselmoinnista arvosanaan vaikuttavan lisäpisteen (huomioidaan viidennen viikon pisteytyksessä).

Jos haluat katselmoida:

  1. Siirry kurssin Moodle-alueelle ja katso, löydätkö kohdasta “Ylimääräinen koodikatselmointi” sellaisia katselmoitavia töitä, joita ei ole vielä varattu katselmointiin. Jos tällainen löytyy, varaa se itsellesi kirjoittamalla nimesi sen perään. Katso, mihin kysymykseen katselmoinnilta erityisesti toivotaan vastausta.
  2. Noudata palautteenannossa pääsääntöisesti koodikatselmoinnin ohjeita (anna palautteesi issueina). Tästä ylimääräisestä katselmoinnista jaettavaan pisteeseen riittää kaksi laadukasta ja rakentavaa palautekommenttia ja yksi käyttökelpoinen parannusehdotus. Näihin tulee sisältyä oma vastauksesi katselmointia toivovan kysymykseen. Kirjoita issueiden otsikoiksi “Koodikatselmoinnin” sijaan “Ylimääräinen koodikatselmointi”.
  3. Lisää työsi README.md -tiedoston loppuun lihavoitu teksti “Ylimääräinen koodikatselmointi” ja linkki katselmoimaasi työhön. Labtooliin ei tarvitse kirjata tästä mitään.

Jos haluat katselmointia: Siirry kurssin Moodle-alueelle ja lisää kohtaan “Ylimääräinen koodikatselmointi” linkki repositorioosi. Kirjoita linkin jälkeen yksi kysymys, johon erityisesti toivoisit katselmoinnilta vastausta.

Harjoitustyön toimivuus

HUOM: Saadaksesi harjoitustyöstä viikkokohtaiset pisteet, sovelluksen tulee toimia laitoksen tietokoneella ja ohjaajien pitää pystyä se niiltä aukaisemaan! Voit testata tätä millä tahansa Cubbli-tietokoneella, kuten fuksiläppärillä, tai laitoksen tietokoneluokkien tietokoneilla. Testaus onnistuu myös virtuaalityöasemassa joko selaimen tai VMWare Horizon -asiakasohjelman avulla.

Virtuaalityöasemassa oman sovelluksen testaaminen onnistuu selaimen avulla seuraavasti:

  1. Kirjaudu virtuaalityöasemaan ja valitse Cubbli Linux
  2. Käynnistä terminaali ja tarkista käytössäoleva Python-versio komennolla python3 --version. Jos versio on alle 3.8, päivitä versio tämän ohjeen avulla
  3. Varmista, että Poetry on asennettu suorittamalla komento poetry --version. Jos asennus puuttuu, seuraa näitä Linux-asennuksen ohjeita
  4. Kloonaa repositoriosi haluamaasi hakemistoon git clone-komennolla
  5. Siirry repositoriosi hakemistoon ja asenna riippuvuudet komennolla poetry install. Huomaa, että komento tulee suorittaa hakemistossa, jossa pyproject.toml-tiedosto sijaitsee

Mikäli yhteys virtuaalityöasemaan pätkii, kannattaa kokeilla toista selainta. Käyttäjät ovat raportoineet ainakin Google Chromen toimivan varsin hyvin. Myös VMWare Horizon Clientin asentaminen saattaa auttaa.

HUOM: Jos suoritat SQLite-tietokantaa käyttävää sovellusta virtuaalityöasemassa, saatat törmätä virheeseen database is locked. Ongelma ratkeaa luultavasti tämän ohjeen avulla.

Älä plagioi tai riko tekijänoikeuksia

Plagiointi

Kurssilla seurataan Helsingin yliopiston opintokäytäntöjä. Plagiarismi ja opintovilppi, eli esimerkiksi netissä olevien tai kaverilta saatujen vastausten kopiointi ja niiden palauttaminen omana työnä on kiellettyä. Todettu opintovilppi johtaa kurssisuorituksen hylkäämiseen ja toistuva opintovilppi voi johtaa opinto-oikeuden määräaikaiseen menettämiseen.

Mitä plagiointi tarkoittaa harjoitustyön yhteydessä? Koodin suora kopioiminen on kiellettyä poikkeuksena muutaman rivin mittaiset algoritmit ja ChatGPT:n tai vastaavien välineiden generoima koodi (ks. alla). Myös koodin rakenteen suora kopioiminen esim. siten että muuttujien ja funktioiden nimet muutetaan lasketaan plagioinniksi. Toisaalta esim. verkosta löytyneitä kuvia saa käyttää, jos tähän on oikeus (ks. kohta tekijänoikeudet), mutta näin tehtävessä tulee työn dokumentaatioon tehdä “lähdeviite”, eli mainita mistä lainaus on tehty.

Samat plagiaattisäännöt koskevat työn dokumentaatiota ja erityisen kiellettyä on copy pasteta referenssisovelluksen dokumentaatiota.

ChatGPT ja vastaavat

Myös ChatGPT:n ja vastaavien tekoälyyn perustuvien välineiden (kuten esim. Microsoft Copilotin, Google Geminin, CurreChatin tai GitHub Copilotin) generoiman koodin tai tekstin esittäminen itse kirjoitetuksi on plagiointia. Generoidun koodin käyttö on kurssilla sallittua, mutta “ympäröi” aina tällainen koodi kommenteilla # generoitu koodi alkaa ja # generoitu koodi päättyy. Tee näin myös silloin, jos olet tehnyt generoituun koodiin vain vähäisiä muutoksia (vaihtanut muuttujien ja funktioiden nimiä tms.). Toisaalta, jos tämä ei käyttötavasta johtuen tunnu mielekkäältä, voit vaihtoehtoisesti liittää dokumentaatioon kuvauksen siitä, että millä tavoin ja missä laajuudessa olet tekoälypohjaisia välineitä harjoitustyösi missäkin osassa käyttänyt.

Muistathan, että ChatGPT:n ja vastaavien välineiden käyttö yksikkötestien koodin generointiin on kurssilla kiellettyä (muuten saa kyllä käyttää testailtaessakin).

Tekijänoikeudet

Kunnioita muutenkin tekijänoikeuksia ja muita immateriaalioikeuksia. Muista, että et saa käyttää mitä tahansa verkosta löytynyttä omassa työssäsi. Tämä koskee monenlaista materiaalia ohjelmakoodista kuviin ja teksteihin. Tarkista siis aina, että onko käyttö sallittua sen lisenssin mukaan, jolla materiaali mahdollisesti on jaettu. Muista, että harjoitustyöt ovat lähtökohtaisesti julkisia GitHubissa. On omalla vastuullasi, ettet riko tekijänoikeuksia.