Kontrolltöö 1 vormistuse soovitused
NB! Kontrolltöös ei nõuta main-funktsiooni kasutamist, kuid põhiprogramm peaks tulema faili kõige lõppu (pärast kõiki funktsioone).
Kommenteerimine
Robert C. Martin väidab oma raamatus "Clean Code: A Handbook of Agile Software Craftsmanship", et programmeerimisel pole niivõrd oluline igat rida kommenteerida, vaid programm peaks olema kirjutatud ja struktureeritud selliselt, et see on selgesti loetav ja arusaadav. Siiski ei tähenda see, et koodis ei peaks üldse kommentaare olema. Näiteks keerulise funktsiooni kirjutamisel on väga mõistlik teatud ridu kommenteerida, et koodist paremini aru saada. Hea stiil oleks vähemalt funktsioonide juurde kirjutada, mida see funktsioon tegema peab. Koodi struktureerimiseks ja kommenteerimiseks võiks kasutada standardeid PEP 8 ja PEP 257 (vt allpool).
Programmi struktuur
Programmide kirjutamisel on oluline järgida ühtset programmi struktuuri selles järjekorras:
- Moodulite importimine
- Funktsioonide defineerimine
- Põhiprogramm
Moodulite importimine
Programmis vajalike moodulite importimine peaks toimuma programmifaili alguses. Näiteks kui soovime programmis kasutada arvu pii väärtust moodulist math, siis võiks programmi alguses importida konstandi pi selliselt:
from math import pi
Funktsioonide defineerimine
Funktsiooni saab kasutada alles siis, kui see on defineeritud, ehk programm on funktsiooni nn sisse lugenud. Seetõttu on hea stiil panna kõik funktsioonid enne põhiprogrammi tegevusi. Näiteks kui soovime luua funktsiooni, mis leiab ringi pindala, siis võiks see funktsioon olla programmi alguses kohe pärast moodulite importimist. Samuti oleks hea jätta funktsioonide vahele (ja importide ning esimese funktsiooni vahele) 2 tühja rida. Funktsiooni algusesse võiks kirjutada lühikese kirjelduse (docstring, vt allpool). Näide:
from math import pi
def ringi_pindala(raadius):
"""Leiab ringi pindala kahe komakohani ümardatult."""
pindala = pi * raadius ** 2
return round(pindala, 2)
Põhiprogramm
Pärast moodulite importimist ja funktsioonide defineerimist võiks tulla põhiprogramm. Põhiprogrammi saab kirjutada pärast funktsioone selliselt:
from math import pi
def ringi_pindala(raadius):
"""Leiab ringi pindala kahe komakohani ümardatult."""
pindala = pi * raadius ** 2
return round(pindala, 2)
print(ringi_pindala(5))
print(ringi_pindala(10))
Programmi väljund:
78.54 314.16
Main-funktsioon
Kuna põhiprogrammis võib olla mitmeid käsklusi, siis oleks hea need koondada ühte põhifunktsiooni, mille nimi võiks olla main. Sel juhul peaks funktsiooni main programmi lõpus ka välja kutsuma.
Sellisel juhul oleks kogu programm selline:
from math import pi
def ringi_pindala(raadius):
"""Leiab ringi pindala kahe komakohani ümardatult."""
pindala = pi * raadius ** 2
return round(pindala, 2)
def main():
print(ringi_pindala(5))
print(ringi_pindala(10))
main()
Veel parem stiil on kutsuda main() välja if-lauses, et vältida main-funktsiooni käivitamist siis, kui faili teisest failist importida. Kui faili käivitada otse, siis täidetakse main(); kui faili importida, siis mitte. Kogu programm oleks sel juhul selline:
from math import pi
def ringi_pindala(raadius):
"""Leiab ringi pindala kahe komakohani ümardatult."""
pindala = pi * raadius ** 2
return round(pindala, 2)
def main():
print(ringi_pindala(5))
print(ringi_pindala(10))
if __name__ == "__main__":
main()
PS! Kontrolltöös ei nõuta main-funktsiooni kasutamist, aga põhiprogramm võiks tulla kõige lõpus.
Standardid PEP 8 ja PEP 257
Pythoni koodi kirjutamisel on abiks ka standardid. PEP 8 standard kirjeldab näiteks, millised võiksid olla muutujanimed, kuhu asetada tühikud jne: https://peps.python.org/pep-0008/.
Kommenteerimisel tuleb appi standard PEP 257, mis soovitab funktsioonide kommenteerimisel võtta kasutusele docstring. Docstring on kolmekordsetesse jutumärkidesse kirjutatud lühike kirjeldus, mis asub funktsiooni esimesel real kohe pärast funktsiooni päist:
def ringi_pindala(raadius):
"""Leiab ringi pindala kahe komakohani ümardatult."""
pindala = pi * raadius ** 2
return round(pindala, 2)
Rohkem infot PEP 257 ja docstringi kohta leiab aadressilt https://peps.python.org/pep-0257/.