Dokumenteerimine

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

Kommentaar

Kommentaarid on kirjeldused, mida koodilugemisel kompilaator eirab. Kommentaare defineeritakse sümboli # abil ning võib kasutada koodirea vältel. 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 korrektselt, lisatakse rea algusesse kommentaar, mis rea sisse lugemise tühistab.

...

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

...

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 järgnevalt räägitava docstringiga. Mitmerealine kommentaar käib kolme jutumärgi abil, olgu nad siis ühe- või kahekordsed.

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

Docstring

Docstring on atribuut, mis lisatakse iga mooduli, funktsiooni, klassi ning meetodi külge ning mis seletab selle 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) :
    """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, chars) :
    """
    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:

  • kasutatakse kolmkordseid jutumärke (”). Seda isegi juhul, kui kommentaar mahub ühele reale.
  • enne ega peale 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 pikem kirjeldus.
  • kirjelduses kasutatakse pigem käske Return sum, Calculate area, mitte kirjeldusi Returns sum, Calculates area jne.

Täpsemalt docstring‘i kohta saab lugeda siit: https://www.python.org/dev/peps/pep-0257/