(P) Binairon paluu¶

Alkukommentti ja palautteen kieli¶

Samoin kuin aikaisemmin tässäkin projektissa vaaditaan alkukommentti. Mallia voit katsoa ensimmäisen projektin tehtävänannosta (4.5 (P) Binairo). Riittää kirjoittaa alkukommentit niihin tiedostoihin, joihin teet muutoksia.

Kuten edellisissä projekteissa palautteen kieli valitaan palautuslaatikossa (tämän sivun lopussa). Kielivalinta määräytyy ainoastaan sen perusteella, minkä kielivalinnan olet tehnyt viimeisimmän palautuksen palautuslaatikossa.

Pelin säännöt¶

Pelin säännöt ovat hyvin yksinkertaiset: Tavoitteena on saada aikaiseksi pelilauta, joka täyttää seuraavat vaatimukset:

• kullakin vaaka- ja pystyrivillä pitää olla sama määrä nollia ja ykkösiä
• kullakin vaaka- ja pystyrivillä saa olla peräkkäin korkeintaan kaksi samaa lukua.

Alkuperäisessä Binairo-pelissä on vielä kolmaskin sääntö: kaikkien vaaka- ja pystyrivien pitää olla keskenään erilaisia. (Tämän voit toteuttaa lisäominaisuutena.)

Tehtävänanto¶

Tehtävänäsi on toteuttaa graafinen käyttöliittymä binairo-peliin, jonka toimintalogiikka on annettu pohjakoodissa. Käyttöliittymäkoodi pitää toteuttaa nyt graafisesti, eli:

• aloitustavan kysyminen
• aloitustavasta riippuen joko siemenluvun tai syötteen kysyminen
• pelitilanteen näyttäminen ja ei-sallittujen lisäysten estäminen.

Näiden lisäksi pelissä pitää olla:

• mahdollisuus aloittaa peli uudestaan (reset)
• ajastin, joka kertoo tähän mennessä käytetyn ajan.

Voit toteuttaa käyttöliittymän (peli-ikkunan) haluamallasi tavalla. Ruudut voit toteuttaa esimerkiksi etiketteinä (QLabel) tai painonappeina (QPushButton) tai QGraphicsScene-ominaisuutena.

Arvioinnissa kiinnitetään huomiota siihen, miten hyvin käyttöliittymäkoodi on erotettu pelin varsinaisesta toimintalogiikasta. Toimintalogiikkahan on jo (pääosin) valmiiksi toteutettu, joten periaatteessa riittää, että kirjoitat kaiken käyttöliittymäkoodin luokkaan MainWindow. Todennäköisesti tarvitset kuitenkin lisää funktioita muuallekin. Jos lisäämäsi funktiot eivät mitenkään käsittele käyttöliittymää, ne kannattaa lisätä luokkaan GameBoard. Huomaa, että koodin tulisi olla mahdollisimman lähellä sitä dataa, jota se käsittelee. Kun noudatat tätä periaatetta, voi helposti käydä niin, että jotakin toimintoa varten joudut lisäämään uuden metodin molempiin edellä mainituista luokista.

Luokan GameBoard metodeita voit tarvittaessa siirtää yksityisistä julkisista, tai voit muuttaa void-metodin palauttamaan jonkin sopivan tyyppisen arvon. Huolehdi kaikkien muutosten kohdalla kuitenkin siitä, että ei-graafinen peli toimii kuten ennenkin.

Minimivaatimukset¶

Toteuttamalla minimivaatimukset voit saada työstä maksimissaan 50 pistettä. Ainakin seuraavat ominaisuudet pitää toteuttaa:

• Pelin pelaamiseksi peli-ikkuna ja peliruudukko näytetään käyttäjälle.
  • Näiden pitää olla graafisia käyttöliittymäkomponentteja (esim. painonappeja/suorakulmioita/neliöitä/etikettejä), ei pelkästään tekstiä.
  • Riittää saada näkyviin nollat ja ykköset numeroina edellä mainittuihin käyttöliittymäkomponentteihin.
• Käyttäjän pitää pystyä valitsemaan aloitustapa (pelilaudan täyttäminen satunnaisesti tai annetulla syötteellä).
  • Tämän voit tehdä esim. painonappia klikkaamalla, näppäinkomennoilla, valintanapeilla tms.
• Peliruudukon kokoa pystyy säätämään, mutta riittää, että sen tekee vaihtelemalla ohjelmakoodissa olevan vakion arvoa (NUMBER_OF_SYMBOLS pohjakoodin tiedostossa gameboard.hh rivillä 13). Muista kertoa dokumentissa vakion nimi on ja sijainti.
  • Tämän pitäisi toimia jo suoraan, kunhan muistat käyttää edellä mainittua vakiota koodissasi.
  • Ota huomioon edellinen vaatimus. Ohjelma ei saa kaatua siihen, että aloituksessa annettu syöterivi olisi väärän pituinen pelilaudan kokoon nähden.
• Pelitilanne pitää näyttää käyttäjälle (tyhjät ja täytetyt ruudut).
• Pelin pystyy aloittamaan uudelleen alusta (reset). Tämän tulee olla mahdollista pelin päätyttyä ja myös kesken pelin.
• Pelin päättyessä ohjelma kertoo käytetyn ajan.
• Pelin toiminnallisuus pitää määritellä ja dokumentoida. Dokumentin pitää sisältää käyttöohjeet pelin pelaamiseen, esimerkiksi millaisia riippuvuuksia eri toiminnoilla on. Dokumentista pitää tulla ilmi, mitä tapahtuu ja mitä voi tapahtua eri tilanteissa. Dokumentissa pitää kuvata myös ohjelman rakenne ja tehdyt suunnittelupäätökset.

Yllä olevat kohdat on siis pakko toteuttaa jollakin tavalla toimivasti. Mitä paremmin olet toteuttanut ne ja mitä paremmalla ohjelmointityylillä, sitä enemmän saat pisteitä.

Saadaksesi enemmän pisteitä kiinnitä huomiota myös pelin käyttäjäystävällisyyteen. Voit esimerkiksi säädellä, ovatko painonapit tai muut käyttöliittymäkomponentit käyttökelpoisia vai eivät (enabled/disabled). Tähän tarkoitukseen luokassa QWidget on slotit setEnabled ja setDisabled.

Erityisen tärkeää on kiinnittää huomiota pelin vakauteen (robustness). Tällä tarkoitetaan sitä, että ohjelma toimii järkevästi (eikä esimerkiksi kaadu), vaikka käyttäjä tekisi jotakin typerää. Esimerkiksi painonappien tapauksessa voit muuttaa käyttökelvottomiksi ne painonapit, joita ei pysty järkevästi käyttämään kyseisessä tilanteessa. Yritä muutenkin etukäteen miettiä, millaisia käyttötilanteita voisi olla. Testaa ohjelmaa kuvittelemalla, että olisit pahantahtoinen vihollinen, joka haluaa saada ohjelman kaatumaan. Jos onnistut tässä, korjaa koodiasi niin, että tällainen tilanne tulee estettyä.

Myös nimeämiskäytäntöihin kiinnitetään huomiota. Tosin Qt:n automaattisesti generoimat nimet eivät aina noudata tyylisääntöjä. Esimerkiksi jos slot generoidaan automaattisesti, nimeksi voi tulla vaikkapa on_pushButton_clicked. Tämä ei ole hyvän ohjelmointityylin mukaista, koska siinä on käytetty molempia tapoja erotella sanoja: alaviivaa ja CamelCase-tyyliä. Käytä kuitenkin itse nimeämissäsi tunnisteissa yhtenäistä tyyliä.

Lisäominaisuudet¶

Kuten edellä kerrottiin, minimiominaisuudet toteuttamalla voit saada maksimissaan 50 pistettä. Toteuttamalla lisäominaisuuksia voit saada maksimissaan toiset 50 pistettä. Vain toimivista ja dokumentoiduista lisäominaisuuksista saa pisteitä, eli myös lisäominaisuudet pitää dokumentoida.

Arvioidessaan projekteja assistentit lisäävät bonuspisteet Plussan myöhempään osioon. Assistentit kiinnittävät huomiota sekä lisäominaisuuksien toimivuuteen että niiden ratkaisutapaan eli siihen, miten tyylikkäästi ratkaisu on toteutettu koodissa.

Esimerkkejä lisäominaisuuksista on lueteltu alla (suuntaa antavat maksimipisteet on kerrottu suluissa):

1. Pelimerkit on toteutettu kuvina (esim. musta ja valkoinen pallura nollan ja ykkösen sijaan). (10 p.)
   • Jotta saisit kuvat käyttöön oikealla tavalla (eli jotta saisit pisteitä kyseisestä lisäominaisuuksista), noudata alla olevia ohjeita:
     1. Klikkaa projektin nimeä (binairo_gui) hiiren oikean puoleisella napilla. Avautuvasta valikosta valitse Add New … -> Qt -> Qt Resource File.
     2. Add Prefix (nimeksi esim. pictures).
     3. Paina Add Files.
     4. Ohjeet kuvina
2. Käyttäjä voi asettaa pelilaudan koon käyttöliittymässä. (5 p.)
3. Pelissä on kolmaskin aloitustapa: Ratkeava syöterivi arvotaan satunnaisesti. (15 p.)
   • Tätä varten tarvitset tiedoston, jonne kokoat ratkeavia syöterivejä, ja niistä arvotaan yksi.
   • Voit käyttää joko oletustiedostoa tai käyttäjän antamaa tiedostoa. Jos toteutat molemmat tavat, voit saada 5 lisäpistettä eli yhteensä 20 p.
   • Ota huomioon, että minimivaatimusten mukaan pelilaudan kokoa voidaan muutella. Riittää kuitenkin, että oletustiedoston käyttö onnistuu vain jonkin tietyn kokoisella pelilaudalla. Ohjelma ei saa kuitenkaan kaatua, vaikka pelilaudan koko ja syötetiedoston rivin pituus eivät täsmäisi.
4. Peli antaa tehdä virheellisen lisäyksen, mutta näyttää tämän virheen jotenkin graafisesti (esim. punaisella). (15 p.)
5. Pelissä on jonkinlainen pistelasku, jonka voit itse valita. Muista dokumentoida pistelaskutapasi. (15 p.)
6. Peli sisältää tulostaulun, johon tallentuu eri pelaajien saamat tulokset (pisteet). Tallennetut tiedot säilyvät pelistä toiseen (eli ne tallennetaan tiedostoon). (10 p.)
7. Käyttöliittymän taustaväri vaihtuu, kun peli loppuu. Uudelleenaloituksessa (reset) taustaväri palautuu ennalleen. (5 p.)
8. Pelissä on pause-nappula, jolla ajanoton saa pysäytettyä, kun peli on käynnissä. Tällöin peli lakkaa esim. vastaamasta näppäinkomentoihin. Käyttäjälle ilmoitetaan jotenkin, että pause on meneillään. (10 p.)
9. Ei-GUI-ominaisuus: peliin on toteutettu myös kolmas sääntö eli kaikkien vaaka- ja pystyrivien pitää olla erilaisia. (10 p.)
10. Ohjelmassa on Help-nappula tms., jonka avulla saa näkyville peliohjeet. (10 p.)
11. Ohjelmassa on erillinen ikkuna, jossa annetaan aloitustapa, tai jokin muu asia on tehty erillisessä ikkunassa. (15 p.)

Voit myös itse ehdottaa haluamaasi lisäominaisuutta. Ehdotukset on tehtävä vähintään viikko ennen työn deadlinea. Lisäominaisuutta voi ehdottaa harjoitustuntien päätteeksi tai lähettämällä viestiä kurssin sähköpostiosoitteeseen. Kurssin henkilökunnalla on oikeus hyväksyä/hylätä ehdotettu lisäominaisuus ja määrätä sille maksimipisteet. Hyväksytyt lisäominaisuudet lisätään yllä olevaan listaan.

Huomaa, että toteuttamalla kaikki edellä luetellut ominaisuudet näyttäisi siltä, että voisit ansaita enemmän kuin 50 pistettä. Kuitenkin voit enintään saada 50 pistettä, sillä jos olisit saamassa enemmän, pisteesi vähennetään 50 pisteeseen. Silti on kannattavaa yrittää toteuttaa ominaisuuksia niin paljon, kuin pystyt, sillä todennäköisesti et saa kaikista lisäominaisuuksista täysiä pisteitä. (Huomaa, että kurssin loppupuolella projektien arvostelukriteerit ovat tiukempia kuin alkupuolella.)

Työn testaaminen ja käyttöohje¶

Tässä projektissa olet itse päävastuussa ohjelmasi riittävän kattavasta testaamisesta. Työ pitää silti palauttaa Plussaan, jotta saisit sen arvioitavaksi. Huomaa, että ohjelman pitää toimia Linux-desktopilla.

Plussa-palautuksessa tarkistetaan, että ohjelma kääntyy, jolloin siitä saa yhden pisteen. Nollan pisteen palautus ei mene assareiden arvioitavaksi.

Luo työhakemistoon tiedosto nimeltä instructions.txt ja kirjoita siihen lyhyt käyttöohje, joka kuvaa pelin säännöt ja ohjelman toimintaa riittävällä tarkkuudella, että assistentti pystyy testaamaan työtä ja arvioimaan sen. Katso minimivaatimuksista, mitä muuta dokumentin pitää sisältää. Muista lisätä tämä tiedosto myös versionhallintaan.

Jos käytät versionhallintaa komentoriviltä, dokumenttitiedoston saa versionhallintaan kuten minkä tahansa muunkin tiedoston. Jos käytät versionhallintaa Qt:n kautta, saat lisättyä dokumenttitiedoston Qt-projektiin seuraavasti. Qt:n editointitilan vasemmalla puolella on lueteltu projektiin kuuluvat tiedostot. Klikkaa hiiren oikealla näppäimellä tiedostolistan yläpuolelta projektin nimeä ja valitse avautuvasta valikosta Add Existing Files ... (jos tiedosto instructions.txt on jo olemassa) tai Add New ... (jos olet vasta alkamassa kirjoittaa kyseistä tiedostoa).

Jos olet toteuttanut lisäominaisuuksia, mutta et ole maininnut niitä tiedostossa instructions.txt, et saa lisäominaisuuksista pisteitä.

Yleisiä vihjeitä¶

• Kannattaa tutustua tämän kierroksen esimerkkeihin. Niiden koodista löytyy useita kohtia, joita voit hyödyntää tässä projektissa.

• Kun lisäät widgettejä tiedostoon mainwindow.ui, ne eivät välttämättä asemoidu oikein suhteessa mahdollisiin koodissa luotaviin widgetteihin. Yritä sijoittaa widgetit niin, että visuaalinen ulkoasu on mahdollisimman hyvä valmiissa käyttöliittymässä.

• Vaikka lisäisitkin widgettejä Qt Designerissa (mainwindow.ui), säädä niiden ominaisuudet koodissa, sillä Qt Designerin säädöt eivät välttämättä tule näkyviin oikein ajettavassa ohjelmassa.

• Peliä toteuttaessasi joudut todennäköisesti turvautumaan Qt:n dokumentaatioon. Sieltä löytyy hyödyllisiä funktioita erilaisten ominaisuuksien toteuttamiseen.

• Kannattaa hyödyntää versionhallintaa myös kokeiluissa. Kun edellinen toimiva versio ohjelmakoodista on tallennettuna keskustietovarastoon, voit huoletta tehdä suurempiakin kokeiluita, kun tiedät, että edellisen version saa aina palautettua. Tämä onnistuu seuraavasti (kullekin muutetulle tiedostolle):

  • Qt:ssa: Tools -> Git -> Current File -> Undo Unstaged Changes / Undo Uncommitted Changes
  • Komentoriviltä: git checkout – <tiedoston nimi>

  Lisätietoa löytyy Plussan Git-kurssilta.

Erityisvaatimukset¶

Seuraavia vaatimuksia on noudatettava, mikäli haluaa työstä hyväksytyn arvosanan:

• Ohjelmassa ei saa olla muistinhallintaan liittyviä virheitä. Kannattaa siis suorittaa valgrind.
  • Jos varaat muistia komennolla new, muisti pitää vapauttaa komennolla delete, ellei vapauttaminen tapahdu parent-child -mekanismin kautta (ks. kierroksen 11 kohta Widgeteistä).
• Ohjelmassa pitää käyttää annettua koodipohjaa, eli pelin pitää perustua siihen. Vaihtoehtoisesti voit käyttää omaa 1-projektiasi pohjana.
• Vain STL-kirjaston säiliöt sallitaan, ei esim. Boost-kirjaston.

Arviointi¶

Jotta työ päätyisi assistenttien arvioitavaksi, se pitää palauttaa Plussaan, ja sen pitää läpäistä automaattitestit. (Tässä tapauksessa automaattitestit tarkistavat vain sen, että ohjelma kääntyy.) Jos saat automaattitesteistä 0 pistettä, myös lopullinen pistemääräsi on 0, eikä työ mene assistenttien arvioitavaksi.

Assistentti arvioi ja pisteyttää automaattitestit läpäisseistä (= 1 p) sekä tehtävänannon erityisvaatimukset täyttävistä töistä viimeisimmän Plussa-palautuksen, joka on tehty määräajan loppuun mennessä, seuraavien arviointikriteerien mukaan:

• Toteutetun ohjelman toiminnallisuus ja käyttöohje 0-10 pistettä:
  • Kaikki minimivaatimuksissa kerrotut ominaisuudet on toteutettu, ja ne toimivat.
  • Ohjelma ei kaadu.
  • Käyttöohjeessa on kerrottu pelin säännöt sekä kuvattu toteutetut lisäominaisuudet. Käyttöohje on kirjoitettu riittävän selvästi, että assistenttien on helppo sitä ymmärtää.
  • Ohjelma toimii käyttöohjeen mukaisesti.
• Ratkaisun yleisperiaate: 0-30 pistettä:
  • Tehtävän osaamistavoitteet on saavutettu.
  • Ohjelmakoodi on jaettu funktioita, luokkia ja/tai metodeita käyttäen loogisiksi kokonaisuuksiksi, jotka ovat sopivan pituisia.
  • Jos luokkia ja olioita on käytetty, ne on toteutettu olio-ohjelmoinnin periaatteita noudattaen (ks. 4-kierroksen Tyyliseikoista kohta Olio-ohjelmointi). Käyttöliittymä on erotettu pelin toimintalogiikasta.
  • Tietorakenne ei sisällä toisteista tietoa eikä turhaa tietoa. Valittuja tietorakenteita on käytetty järkevästi.
  • Ohjelmakoodi ei sisällä turhaa toisteisuutta eikä muutakaan turhaa.
  • Ohjelmakoodi ei sisällä tarpeettomia rajoitteita tai oletuksia tai muita väkinäisiä ratkaisuita.
  • Ohjelmarakenteet on toteutettu helposti ymmärrettäviksi.
  • Ohjelmakoodissa ei ole käytetty globaaleja muuttujia (globaalit const-vakiot ovat OK).
  • Ohjelman toimintaa ei lopeteta exit-funktiota käyttäen.
  • Ohjelmassa ei ole muistinhallintaan liittyviä virheitä (suorita valgrind)
• Ohjelmointityyli: -20-0 pistettä:
  • Muuttujat ja funktiot nimetty selkeästi ja kuvaavasti. Nimeämisessä on käytetty vain yhtä kieltä, ei esim. suomea ja englantia sekaisin.
  • Ohjelmassa on käytetty imettyjä vakioita taikalukujen sijasta.
  • Ohjelmakoodi on asemoitu siististi.
  • Ohjelmakoodirivit ovat enintään 80 merkkiä pitkiä.
  • Jokaisen itse kirjoittamasi/editoimasi tiedoston alussa on kommentti, josta käy ilmi tiedoston tarkoitus, nimesi, opiskelijanumerosi ja muut tarvittavat tiedot. (Tarvittaessa katso mallia ensimmäisen projektin tehtävänannosta.)
  • Jokaisen funktion/metodin alussa (otsikkotiedostossa jos sellainen on olemassa) on kommentti, joka kuvaa sen toiminnan, paluuarvon ja parametrit.
  • Kommentteja on muutenkin tarpeellisissa kohdissa.
  • Kommentit liittyvät toteutettuun ohjelmaan eivätkä johonkin sen vanhempaan versioon.
  • Kaikki kommentit on kirjoitettu samalla kielellä (fi/en), mutta kommentoinnissa saa käyttää eri kieltä kuin muuttujien ym. nimissä.
  • Kaikki muuttujat on alustettu.
  • Kääntäjä ei anna koodia käännettäessä varoituksia.
• Versionhallinnan käyttö: 0-10 pistettä:
  • Committeja on riittävä määrä.
  • Commit-viestien sisältö on selkeä ja kuvaava.

Huomaa yllä olevasta listasta, että tässä vaiheessa tyyliseikkojen oletetaan olevan opiskelijoilla hallussa. Enää et siis saa pisteitä tyylisääntöjen noudattamisesta, vaan niiden käyttämättä jättämisestä sakotetaan. Kannattaa siis tarkistaa, mitä tyyliasioista on kerrottu kierroksilla 4 ja 10.