Tämä on käsiteltävä heti:
siis,
ennenkuin siirrymme opiskelemaan ja kirjoittamaan Python-ohjelmia.
Jotta opiskelu lähtee heti oikeaan suuntaan pitää koodin kirjoittaminen aloittaa oikein:
Dokumentointi ja kommentit
Hyvä koodari kirjoittaa ohjelmakoodin lisäksi ohjelman dokumentit ja kommentit,
jotta hän, tai koodin mahdollinen lukija, ymmärtää mitä ollaan tekemässä.
Dokumentissa ohjelman toiminta kuvataan sanallisesti.
Ohjelman dokumentoinnin merkityksen ymmärtää vasta, kun joutuu muuttamaan omaa yli 6 kk
vanhaa koodia tai korjaamaan jonkun toisen tekemää työtä.
Dokumentointia eli ohjelman toiminnan kuvausta täydennetään koodin sisällä olevilla lisäselvityksillä.
Tällaista selitystekstiä kutsutaan kommentiksi.
Python-ohjelmissa kommenttirivi alkaa risuaita- eli #-merkillä.
Kun Python-tulkki ohjelmaa lukiessaan kohtaa #-merkin,
se ei huomioi koko riviä, paitsi poikkeustapauksissa.
Ei kommentoida itsestäänselvyyksiä,
ainoastaan käskyrivin toimintaa kuvaavalla tekstillä.
Eikä kommentoida kaikkia käskyrivejä. Alussa tuo sallitaan, koska se auttaa opiskelussa.
Kommentit ovat osa ohjelman dokumentointia.
Ne ovat vain koodaajaa ja koodin lukijaa varten, niitä ei Python-tulkki noteeraa mitenkään.
Kommenttien järkevä käyttö helpottaa huomattavasti ohjelmaa lukevaa ihmistä koodin toiminnan ymmärtämisessä.
Vaikka ensi viikolla vielä muistatkin mitä olit tekemässä,
mutta kuukausien/vuosien jälkeen asia voi olla toisin.
Jos vaikka haluat lisätä ohjelmaasi uusia ominaisuuksia, niin silloin järkevä kommentointi on kullan arvoinen.
Hyvä ja riittävä dokumentointi, ovat toimia joilla kunnon koodarit erottuvat sekamiehistä.
Liian pitkä ja yksityiskohtainen dokumentaatio on raskasta lukea ja sen ylläpito on äärimmäisen työlästä.
Ensimmäisen Python-koodin kirjoittaminen
Oletus:
Sinulla on RasPi tietokone etäkäytössä, eli olet tehnyt asetukset jotka on kerrottu dokumentissa RasPin käyttöönotto ,
ja olet tutustunut Thonny-IDEen.
Käynnistä RasPi. Käynnistä pöytäkoneessa VNC-Viewer-etäkäyttöohjelma.
RasPin käyttöliityntä ilmestyy pöytäkoneen näytölle. Käynnistä Thonny.
Heti opiskelun alussa on tärkeää oppia oikeat työmenetelmät. Siispä sovitaan, että toimit näin:
Jokainen ohjelmasi sisältää aluksi kommenttirivejä, joissa on vähintään seuraavat tiedot ohjelmasta:
** projektin ja tiedoston (siis ohjelman) nimi,
** mille ”raudalle”, HW, hardware, koodi on kirjoitettu
** millä kääntäjällä/tulkilla lähdekoodi käännetään
** päiväys, milloin ohjelma tallennettu/muutettu
** tekijän nimi tai nimilyhenne
** lyhyt kuvaus mitä ohjelma tekee
Tehdään mallipohja jolla päästään koodien kirjoituksessa nopeasti alkuun.
Muutat vain muuttuvat tiedot ja that’s it.
Tämä on vain malliksi. Jokainen tekee oman mieltymyksen mukaisen.
Tämä tallennetaan Raspin pi-hakemistossa olevaan Python-koodit-kansioon nimellä pohja.py.
Ota käyttöön aina kun aloitat uutta koodia tekemään.
Muista tallentaa ensiksi, “File, Save as.. “ ja anna sitten ko koodin nimi.
Eli älä tuhoa pohja.py, sitä tarvitaan jatkuvasti.
Näin menetellen omaksut heti oikean tavan tehdä ohjelmia ja tulet - muut ohjelmoijat etenkin - arvostamaan sitä myöhemmin,
kun harrastuksesi muuttuu ammatiksi.
Ja kaikki koodimme ovat samalla formaatilla tehtyjä.
Tämä tuo ryhtiä ja järjestelmällisyyttä koodaustyöhömme.
Miksi Python-ohjelman alussa aina ovat rivit:
#!/usr/bin/env python
# -*- coding: utf-8 -*-
Kaikki skriptit Unixissa alkavat shebang-merkillä.
Python-ohjelma on skripti ja siksi se alkaa aina rivillä jonka kaksi ensimmäistä merkkiä ovat nimeltään shebang, #!
Sitten seuraa polkumääritys, jossa kerrotaan mistä löytyy Python-tulkki.
Shebang on toiselta nimeltään hashbang.
Tästä merkistä tulkki tietää, että kaikki seuraava data on käännettävä konekoodiksi rivi kerrallan,
paitsi jos rivi on määritetty kommentiksi.
Shebang ei toimi Windowsissa.
Jotta voisimme käyttää kommenteissa ääkkösiä (ä, ö, å) ja muita skandinaavisia merkkejä,
meidän tulee kertoa python-tulkille käytetystä merkistöstä.
Toinen rivi kertoo, että käytämme utf-8-merkistökoodia joka mahdollistaa kommenteissa “ääkkösten” käytön.
Itse koodissa ja koodin nimessä ei “ääkkösiä” saa käyttää.
Unicode on tietokonejärjestelmiä varten kehitetty merkistöstandardi.
Niitä on moneen lähtöön, me käytämme utf-8-merkistöä.
Se on osittain yhteensopiva vanhempien järjestelmien kanssa.
Suomen kielen ä ja ö eivät kuulu ASCII-merkistöön jota Python-tulkki käyttää oletuksena.
Jos tuota määritystä ei laiteta ennen kommenttirivejä,
Python-tulkki hermostuu kommentin ääkkösistä ja antaa virheilmoituksen.
Siksi rivi on oltava heti shebang-rivin jälkeen.
Oikeastaan, kun työskentelemme Thonny-editorilla,
ei noita kahta riviä tarvita lainkaan.
Mutta kun opiskelemme tekemään “oikeita töitä” ja silloin koodin ajoympäristö todennäköisesti on toisenlainen,
niin silloin nuo rivit ovat tarpeen.
Tällainen meidän VNC-etäohjelman työpöytä näyttää, kun olet kirjoittanut, tallettanut ja "ajanut" pohja.py-tiedoston Thonny-editorilla.
Ja eikun koodaamaan.