Dokumenteerimine

Selles peatükis räägime, kuidas korrektselt dokumenteerida enda koodi ning miks seda teha tuleks. Lisaks räägime ka koodi kommenteerimise korrektsest stiilist.

Korrektne dokumenteerimine garanteerib koodilugejale koodiplokkide, funktsioonide ja muu sisu lihtsa mõistmise. Programmeerimise vallas toimub tihti projektide üleandmist või lahti seletamist teistele isikutele, kes koodist võimalikult kiiresti aru saama peavad. Selleks kasutatakse kommentaare ning docstringe.

Kommentaar

Kommentaarid on koodikirjeldused, mida kompilaator koodilugemisel eirab. Kommentaarid peaksid olema täislaused ning algama suure algustähega. Kommentaare defineeritakse sümboli # abil. Lisades # rea algusesse, eiratakse tervet koodirida. Kui sümbol ei paikne rea alguses, loetakse sellele eelnev kood ikkagi sisse. Kommentaar algab tühikuga ning kui kommentaar rea keskele lisada, peab koodi lõpu ning # sümboli vahele jätma vähemalt 2 tühikut.

Näide koodirea alguses olevast kommentaarist:

check = False
# Boolean to check whether all elements in a list are correctly sorted.

Näide koodirea lõpus olevast kommentaarist:

x += index  # Increase x by the value of index

Kommentaare kasutatakse sageli ka testitava koodi eiramiseks. Juhul kui koodirida ei ole valmis või ei tööta ajutiselt korrektselt, lisatakse rea algusesse kommentaar (kood kommenteeritakse välja).

# x = very_complex_function()
# This row and the row above will be ignored.

Attention

Lisainfona võib välja tuua, et Pythonis on olemas ka mitmerealine kommentaar, kuid PEP 8 koodistiil ei soovita selle kasutamist, kuna see sarnaneb väga docstringiga, mida vaatame järgmises alampeatükis. Mitmerealine kommentaar käib kolme jutumärgi vahele, olgu nad siis ühe- või kahekordsed jutumärgid.

Näide mitmerealisest kommentaarist:

'''
This is a multiline
comment.
'''

"""
This is also a multiline
comment.
"""

Docstring

Docstring on atribuut, mis lisatakse iga mooduli, funktsiooni, klassi ning meetodi külge ning mis seletab selle konkreetse elemendi sisu. Docstring defineeritakse kolme jutumärgipaari abil ning see saab olla ühe- või mitmerealine.

Üherealine docstring seletab lühidalt elemendi (nt funktsiooni) sisu.

def find_max_in_list(some_list: list):
    """Find and return the maximum value in some_list."""
    # Code

Mitmerealine docstring seletab elemendi sisu pikemalt lahti. Funktsiooni puhul lisatakse informatsiooni iga kaasaantud muutuja ning tagastatava väärtuse kohta.

def check_for_not_allowed_characters(text: str, chars: list) -> bool:
    """
    Check whether String text contains characters from List chars.

    :param text: String to be checked.
    :param chars: List containing not allowed characters.
    :return: Returns True when String text does not contain any
    characters from List chars. Otherwise returns False.
    """
     # Code

Mõned punktid, mida tuleb järgida docstring'i kirjutamisel:

  • Docstring'is kasutatakse kolmekordseid jutumärke """. Seda isegi juhul, kui kommentaar mahub ühele reale.

  • Enne ega pärast docstring'i ei ole tühje ridu. Docstring järgneb vahetult mooduli, funktsiooni, klassi või meetodi definitsioonile. Mooduli või klassi puhul järgneb kirjeldusele tühi rida.

  • Mitmerealise kirjelduse puhul peab esimene rida olema lühike kokkuvõte, mis lõppeb punktiga. Sellele järgneb tühi rida ning seejärel võib tulla elemendi pikem kirjeldus.

  • Kirjelduses kasutatakse täislauseid käskivas kõneviisis (ingl k imperative), näiteks sobib stiil Return sum, kuid ei sobi kirjeldus Returns sum.

Rohkem lugemist