Pythoni programmeerimise maailm

Python docstring’id: täielik juhend kirjutamiseks ja parimate tavade järgimiseks

Erandite ja vigade käsitlemine
目次

1. Mis on Pythoni docstring?

Pythonis on docstring eriline string, mida kasutatakse funktsioonide, klasside ja moodulite dokumenteerimiseks. docstring parandab koodi hooldatavust ja aitab teistel arendajatel seda kiiremini mõista. Lisaks saab automaatseid dokumentatsioonitööriistu (nt Sphinx) kasutades docstringist genereerida põhjalikku dokumentatsiooni.

docstring’i asukoht ja vorming

docstring paigutatakse kohe funktsiooni, klassi või mooduli definitsiooni järele ning see ümbritsetakse kolmikute topeltjutumärkidega. Üldine süntaks on järgmine:

def funktsiooni_nimi(argumendid):
    """
    Siia kirjutatakse lühikirjeldus funktsiooni eesmärgist.

    Argumendid:
        arg_nimi (tüüp): detailsem kirjeldus argumendist
    Tagastus:
        tüüp: tagastatava väärtuse kirjeldus
    """
    pass

docstringi kasutatakse nii Pythoni sisseehitatud funktsioonis help() kui ka koodiredaktorites, kus see pakub lisaselgitusi. Seetõttu on selle roll dokumentatsioonina väga oluline.

2. docstring’i põhiline kirjutamisviis

Pythonis kasutatakse docstringit selleks, et lühidalt ja selgelt kirjeldada funktsiooni või klassi käitumist. Tüüpiliselt algab see funktsiooni eesmärgi lühikirjeldusega, millele järgneb info argumentide, tagastusväärtuste ja võimalike vigade kohta. Kui järgida Pythoni ametlikku stiilijuhendit PEP 257, säilib ühtlane stiil ja kood muutub teistele arendajatele arusaadavamaks.

docstring’i põhiline struktuur

Üherealine docstring sobib siis, kui funktsiooni saab kirjeldada väga lühidalt. Näiteks:

def add(a, b):
    """Kahe arvu summa tagastamine."""
    return a + b

Mitmerealist docstringit kasutatakse detailsemaks seletuseks. Seal kirjeldatakse funktsiooni tööd, argumente ja tagastusväärtusi, kasutades reavahetusi loetavuse suurendamiseks:

def add(a, b):
    """
    Liidab kaks arvu ja tagastab tulemuse.

    Argumendid:
        a (int): esimene liidetav arv
        b (int): teine liidetav arv

    Tagastus:
        int: kahe arvu summa
    """
    return a + b

 

年収訴求

3. docstring’i stiilid (Google stiil, NumPy stiil, reStructuredText stiil)

docstringitel on erinevad stiilid sõltuvalt projektist või tööriistadest, mida kasutatakse. Kõige laialdasemalt levinud on Google stiil, NumPy stiil ja reStructuredText stiil.

Google stiil

Google stiil on tuntud oma lihtsuse ja visuaalse selguse poolest. Argumendid ja tagastusväärtused kirjeldatakse jaotiste Args ja Returns all, mis muudab funktsiooni eesmärgi kiirelt arusaadavaks.

def add(a, b):
    """
    Liidab kaks arvu ja tagastab tulemuse.

    Args:
        a (int): esimene liidetav arv
        b (int): teine liidetav arv

    Returns:
        int: kahe arvu summa
    """
    return a + b

NumPy stiil

NumPy stiil pakub detailsemaid seletusi ning seda kasutatakse laialdaselt teadusliku arvutuse ja andmeanalüüsi teekide dokumentatsioonis. Kasutatakse jaotisi nagu Parameters ja Returns.

def add(a, b):
    """
    Liidab kaks arvu ja tagastab tulemuse.

    Parameters
    ----------
    a : int
        esimene liidetav arv
    b : int
        teine liidetav arv

    Returns
    -------
    int
        kahe arvu summa
    """
    return a + b

reStructuredText stiil

reStructuredText stiili kasutatakse koos Sphinxiga, mis on populaarne dokumentatsiooni genereerimise tööriist. Selle abil saab koodist automaatselt luua HTML- või PDF-dokumente.

def add(a, b):
    """
    Liidab kaks arvu.

    :param a: esimene liidetav arv
    :type a: int
    :param b: teine liidetav arv
    :type b: int
    :return: kahe arvu summa
    :rtype: int
    """
    return a + b

 

4. PEP 257 ja parimad tavad

Pythoni ametlik stiilijuhend PEP 257 kirjeldab selgelt, kuidas docstringeid kirjutada. Selle järgimine parandab koodi loetavust ja muudab selle lihtsamini mõistetavaks nii teistele arendajatele kui ka autorile endale.

Olulised punktid PEP 257-st

  1. Üherealine docstring
    Lihtsate funktsioonide puhul soovitatakse kasutada lühikest ühe realist kirjeldust.
  2. Mitmerealine docstring
    Kui vaja on detailsemat seletust, kasutatakse mitmerealist docstringit. Esimene rida jääb kokkuvõtteks, millele järgneb tühi rida ja siis detailsem kirjeldus.
  3. Taanded ja tühjad read
    docstringis suurendatakse loetavust taanete ja reavahetuste abil. Argumendid ja tagastusväärtused tuleb selgelt eristada.

Parimad tavad

  • Lühike ja selge kirjeldus
    docstring peaks olema kompaktne, kuid samal ajal täpne, et selgitada funktsiooni või klassi eesmärki. Ebaoluline info tuleks välja jätta ja olulised punktid esile tuua.
  • Ühtne stiil
    Projekti sees tuleks kasutada sama stiili (Google, NumPy või muu), et dokumentatsioon oleks ühtlane ja loetav.

5. docstring’i kasutamine testides (doctest)

Pythonis on moodul doctest, mis võimaldab docstringis olevat näidiskoodi automaatselt testida. See suurendab koodi töökindlust ja dokumentatsiooni usaldusväärsust.

doctest’i põhiline kasutamine

doctest otsib docstringidest näidiskoodi ning kontrollib, kas need tagastavad oodatud tulemuse. Näiteks:

def add(a, b):
    """
    Liidab kaks arvu ja tagastab tulemuse.

    Args:
        a (int): esimene arv
        b (int): teine arv

    Returns:
        int: kahe arvu summa

    Näide:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Ülaltoodud näites käivitab doctest funktsiooni ja võrdleb tulemust docstringis oleva väljundiga.

doctest’i eelised

  1. Koodi ja dokumentatsiooni vastavus
    doctest tagab, et dokumentatsioonis olevad näited töötavad päriselt, hoides dokumentatsiooni kooskõlas koodiga.
  2. Automaatne testimine
    Kõik docstringis olevad näited testitakse automaatselt, mis vähendab käsitsi testimise vajadust ja võimalikke vigu.

6. Praktiline näide: docstringi kasutamine koodi dokumenteerimisel

Kui docstringit kasutatakse järjepidevalt, muutub Pythoni kood palju loetavamaks ja lihtsamini mõistetavaks teiste arendajate jaoks. Allpool on toodud näide klassi ja meetodite dokumenteerimisest.

Näide klassi docstring’ist

class Calculator:
    """
    Lihtne kalkulaatori klass.

    See klass võimaldab teha põhitehteid: liitmine, lahutamine, korrutamine ja jagamine.

    Attributes:
        result (int): muutuja arvutustulemuse hoidmiseks
    """

    def __init__(self):
        """
        Calculator klassi konstruktor.
        Algväärtustab tulemuse nulliga.
        """
        self.result = 0

    def add(self, a, b):
        """
        Liidab kaks arvu ja tagastab tulemuse.

        Args:
            a (int): esimene arv
            b (int): teine arv

        Returns:
            int: kahe arvu summa
        """
        self.result = a + b
        return self.result

Selles näites on nii klassil kui ka igal meetodil oma docstring, mis annab kasutajale kiire ülevaate funktsionaalsusest.

Dokumentatsiooni genereerimine Sphinxiga

Sphinx võimaldab docstringite põhjal automaatselt luua HTML- või PDF-dokumente. Selleks tuleb projektis seadistada conf.py fail ja käivitada käsk make html, mis genereerib dokumentatsiooni otse koodist.

Sphinx paigaldatakse käsuga:

pip install sphinx

Seejärel algatatakse projekt:

sphinx-quickstart

Pärast seadistamist luuakse dokumentatsioon automaatselt olemasolevate docstringite põhjal.

7. Levinud vead ja kuidas neid vältida

Algajad teevad docstringeid kirjutades sageli teatud vigu. Allpool on mõned tüüpilised probleemid ja nende lahendused.

1. Liiga ebamäärane kirjeldus

docstring peab olema konkreetne. Näiteks järgmine kirjeldus on puudulik:

def add(a, b):
    """Liidab kaks arvu."""
    return a + b

Puudub info argumentide ja tagastusväärtuse kohta. Parandatud versioon:

def add(a, b):
    """
    Liidab kaks täisarvu ja tagastab summa.

    Args:
        a (int): esimene arv
        b (int): teine arv

    Returns:
        int: kahe arvu summa
    """
    return a + b

2. Argumendi või tagastusväärtuse ebatäpne kirjeldus

Kui argumentide ja tagastusväärtuste tüübid või tähendus pole selged, võib funktsiooni kasutamine muutuda keeruliseks. Näiteks:

def divide(a, b):
    """Jagab kaks arvu."""
    return a / b

See jätab lahtiseks, mis juhtub nulliga jagamisel. Parandatud versioon:

def divide(a, b):
    """
    Jagab kaks arvu ja tagastab tulemuse. Nulliga jagamisel tõstab ZeroDivisionError.

    Args:
        a (float): jagatav
        b (float): jagaja

    Returns:
        float: jagamise tulemus

    Raises:
        ZeroDivisionError: kui b = 0
    """
    if b == 0:
        raise ZeroDivisionError("Nulliga ei saa jagada")
    return a / b

8. Kokkuvõte: tõhus dokumentatsiooni loomine docstringitega

Selles artiklis käsitlesime Pythoni docstringite olulisust, nende kirjutamisviise, stiile ja parimaid tavasid. docstringid parandavad koodi loetavust ja hooldatavust ning PEP 257 juhiste järgimine tagab ühtse ja professionaalse dokumentatsiooni.

Lisaks vaatasime, kuidas kasutada doctestit testimiseks ja Sphinxi dokumentatsiooni automaatseks genereerimiseks. Nende tööriistade abil saab tagada, et dokumentatsioon on alati kooskõlas koodiga ning vähendada vigade tekkimise võimalust.

Ühtne dokumentatsioon vastavalt PEP 257-le

PEP 257 annab ametlikud juhised docstringite kirjutamiseks. Selle järgimine võimaldab luua lihtsasti loetavat ja järjepidevat dokumentatsiooni. Lihtsate funktsioonide puhul sobib ühe realine docstring, detailsemate funktsioonide jaoks aga mitmerealine kirjeldus.

doctest’i kasutamine näidiskoodi testimiseks

doctest võimaldab automaatselt testida docstringites olevat näidiskoodi, tagades dokumentatsiooni ja koodi kooskõla. See aitab ennetada vigu ja parandab töökindlust.

Automaatne dokumentatsiooni loomine Sphinxiga

Sphinx võimaldab docstringite põhjal genereerida HTML- või PDF-vormingus dokumente. See vähendab käsitsi dokumentatsiooni koostamise vajadust ja tagab, et dokumentatsioon püsib alati ajakohane.

—

Lõppsõna: docstringid ei ole lihtsalt kommentaarid koodis, vaid need on väärtuslik tööriist, mis aitab arendajatel luua professionaalse, usaldusväärse ja hooldatava tarkvara.