Dokumenteerimine

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 kirjeldused, mida kompilaator koodilugemisel eirab. 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 keskel olevast kommentaarist:

...

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

...

Kommentaare kasutatakse ka testitava koodi eiramiseks. Juhul kui koodirida ei ole valmis või ei tööta ajutiselt korrektselt, lisatakse rea algusesse kommentaar.

...

# x = very_complex_function()
# The row above will be ignored.

...

Attention

Valgustuse mõttes võib välja tuua, et Pythonis on 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.

'''
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 neid on ühe- ning mitmerealisi.

Ü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:

  • Docstingis kasutatakse kolmkordseid 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 pigem käske Return sum, Calculate area, mitte kirjeldusi Returns sum, Calculates area jne.

Rohkem lugemist