Koodistiil (Coding style)

Mis on 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 kirjutatakse väikeste tähtedega.
• Sõnade eraldajana kasutatakse alakriipsu ( _ ).
• Näiteks: best_score, temperature.
• Mitte kasutada lühendeid (nt temp, a, b).

Funktsioon

• Nimi väikeste tähtedega, sõnade eraldajaks alakriips.
• Näiteks: calculate_area, normalize_name.
• Funktsiooni parameetrite arv võiks olla kuni 4.
• Funktsiooni nimi peaks kirjeldama, mida funktsioon teeb.
• Pikkus tavaliselt kuni 20 rida.

Tühikute kasutamine

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

Docstring

Docstring on kommentaar funktsiooni, meetodi, klassi või mooduli (faili) kohta.

• Kirjeldatakse kolmekordsete jutumärkide ( """ ) vahel.
• Eesmärk on kirjeldada funktsionaalsust.
• Võib olla ühe- või mitmerealine.
• Kasutatakse täislauseid, mis lõppevad 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 docstringi puhul on esimene rida kokkuvõte, millele järgneb tühi rida.

Üherealine docstring

Võib kasutada, kui kirjeldus on lühike:

"""String helper functions."""

• Jutumärgid algavad ja lõppevad samal real.
• Lause peab lõppema punktiga.

Funktsiooni docstring

Kirjutatakse kohe 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)
        

Stiilinõue: Sisu peab olema täislausetena ja esimene lause 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 docstringi esimese ja ülejäänud ridade vahel peab olema tühi rida.
• Rea lõpus ei tohi olla üleliigseid tühikuid.

Standardid

Pythonis on tuntuimad standardid:

• PEP 8 (koodi vormistus)
• PEP 257 (docstringi konventsioonid)

Ülesannete esitamisel kontrollitakse koodi vastavust nendele stiilidele ning vead tuuakse välja tagasiside emailis.