12. Vormistuse soovitused
Kommenteerimine
Robert C. Martin väidab enda 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 standardit.
Programmi struktuur
Programmide kirjutamisel üheks oluliseks osaks on jälgida ühtset programmistruktuuri vastavas 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 pii selliselt:
from math import pi
Funktsioonide defineerimine
Funktsioonide kasutamiseks peab programm need enne väljakutsumist nn sisse lugema. Selleks on hea stiil funktsiooni alati panna 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 2 tühja rida. Näide:
from math import pi
def ringi_pindala(raadius):
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):
pindala = pi * raadius ** 2
return round(pindala, 2)
print(ringi_pindala(5))
print(ringi_pindala(10))
Main-funktsioon
Kuna põhiprogrammis võib olla mitmeid käsklusi, siis oleks hea neid struktuurselt omakorda koondada ühte põhifunktsiooni, mille nimi võiks olla main. See omakorda tähendab, et siis peaks seda funktsiooni main ka programmi lõpus välja kutsuma.
Sellisel juhul oleks kogu programm selline:
from math import pi
def ringi_pindala(raadius):
pindala = pi * raadius ** 2
return round(pindala, 2)
def main():
print(ringi_pindala(5))
print(ringi_pindala(10))
main()
NB! Suurtemate programmmide kirjutamisel oleks hea stiil funktsiooni main() välja kutsuda if-lauseosas "if __name__ == "__main__":", aga meie kursuse automaatkontrollid seda võimalust ei luba!
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 funktsoonide kommenteerimisel võtta kasutusele docstring. Rohkem infot PEP 257 ja docstringi kohta leiab aadressilt https://peps.python.org/pep-0257/.