Koodistiil

Coding style

Koodistiil

  • Kood on korraldused arvutile
  • Arvuti jaoks pole koodistiilil vahet
  • Koodi on vaja hiljem hallata ja täiendada
  • Koodistiil on oluline arendajale

Muutujate nimetamine

  • Muutuja nimi väikeste tähtedega
  • Sõnade eraldajana kasutada alakriipsu _
  • Näiteks: best_score, temperature
  • Mitte kasutada lühendeid (temp, a, b)

Funktsioon

  • Nimi väikeste tähtedega
  • Sõnade eraldajana kasutada alakriipsu _
  • Näiteks: calculate_area, normalize_name
  • Funktsiooni parameetrite arv võiks olla kuni 4
  • Funktsiooni nimi võiks kirjeldada, mida funktsioon teeb
  • Pikkus tavaliselt kuni 20 rida

Tühikute kasutamine

  • Operaatori ees ja järel tühik
    • 3 + 4 * 12
    • age = 18 + additional_years
  • Funktsiooni väljakutsel sulu ees tühikut pole
    • do_something(12), print(1)

docstring

  • docstring on kommentaar
    • Funktsiooni, meetodi, klassi, mooduli (faili) kohta
    • Kirjeldatakse """ märkide vahel pärast funktsiooni, meetodi jne deklaratsiooni
  • docstring'i eesmärk on kirjeldada funktsiooni, meetodit
  • Võib olla ühe- või mitmerealine
  • Täislaused, lõppeb punktiga

docstring faili alguses

  • Faili (mooduli) alguses kirjeldatakse ära, mida see fail teeb
"""
Collection of helper functions for string operations.

Most of the functions work with only ascii strings. 
Check the docstrings for more information.
"""
  • Mitmerealise docstring'i puhul esimene rida on kokkuvõte
  • Kokkuvõttele järgneb tühi rida

Üherealine docstring

  • Võib kasutada üherealist docstring'i:
"""String helper functions."""
  • Jutumärgid algavad ja lõppevad samal real
  • Lause peab lõppema punktiga

Funktsiooni docstring

  • Kirjutatakse peale funktsiooni definitsiooni
def absmax(a: int, b: int) -> int:
    """
    Return a max value of two inputs.

    Absolute values of the inputs are 
    used when comparing.
    Returns original (non-absolute) 
    value.
    """
    return max((a, b), key=abs)

Üherealine docstring

  • Üherealine peab mahtuma ühele reale (koos jutumärkidega)
def longer(a: str, b: str) -> str:
    """Return the longest string."""
    return max((a, b), key=len)

docstring'i stiil

  • Sisu peab olema täislausetena
  • Esimene lause peab olema käskivas kõneviisis (imperative)
    • Sobib: Return sum.
    • Ei sobi: Returns sum.

Üldised stiilinõuded

  • Faili lõpus peab olema tühi rida
  • Funktsiooni ees peab olema 2 tühja rida
  • Mitmerealise docstring'i esimese ja ülejäänud ridade vahel peab olema tühi rida
  • Rea lõpus ei tohi olla üleliigseid tühikuid

Standardid

  • Pythonis on kõige tuntumad kaks standardit:
  • Ülesande lahendusi esitades kontrollitakse koodi vastavust stiilile
  • Tulemuses (emailis) on välja toodud stiilivead, mida tuleks parandada

Stiilivead tulemuses

  • Näidatakse ära fail, rida ja positsioon, kus viga tekkis
  • Veakoodi ja sisu järgi saab otsida, mida viga tähendab