Mundo ng Python Programming

Gabay sa Python docstring: Pagsulat, Estilo, Best Practices

Exception Handling at Kontrol ng Error
目次

1. Ano ang docstring sa Python?

Sa Python, ang docstring ay isang espesyal na string na idinadagdag sa code ng mga function, klase, module, at iba pa upang magbigay ng paliwanag. Ang docstring ay nagpapabuti sa maintainability ng code at naglalaro ng napakahalagang papel upang gawing mas madaling maunawaan ng ibang developer ang code. Bukod pa rito, sa pamamagitan ng paggamit ng mga awtomatikong tool sa pagbuo ng dokumentasyon na tatalakayin mamaya (hal.: Sphinx), maaaring lumikha ng dokumentasyon na gumagamit ng docstring.

Posisyon at Format ng docstring

docstring ay inilalagay kaagad pagkatapos ng definisyon ng function, klase, o module na tinutukoy, at karaniwang nakapaloob sa triple double quotes. Ang sumusunod na syntax ay karaniwan.
def 関数名(引数):
    """
    Isusulat dito ang isang maikling paliwanag ng function.

    Argumento:
        Pangalan ng argumento (uri): Detalyadong paliwanag tungkol sa argumento
    Balik na halaga:
        Uri: Paliwanag tungkol sa balik na halaga
    """
    pass
docstring ay ginagamit din ng built-in function ng Python na help() at sa mga tooltip sa editor, at gumaganap ng malaking papel bilang dokumentasyon ng code.

2. Pangunahing Paraan ng Pagsulat ng docstring

Ang docstring ng Python ay ginagamit upang maipaliwanag nang maikli at malinaw ang mga detalye ng mga function at klase. Bilang format, unang inilalarawan nang simple ang layunin ng function, pagkatapos ay tinatalakay ang mga argumento, return value, at mga error. Sa pagsunod sa opisyal na style guide ng Python na PEP 257, mapapanatili ang pagkakaisa at makakalikha ng code na madaling maintindihan ng ibang developer.

Pangunahing Estruktura ng docstring

Ang isang-linyang docstring ay ginagamit kapag nagbibigay ng napaka-maikling paliwanag. Karaniwan itong ginagamit upang ilarawan ang function sa isang salita, at sinusulat tulad ng sumusunod.
def add(a, b):
    """Nagbabalik ng kabuuan ng dalawang numero."""
    return a + b
Ang multi-line na docstring ay ginagamit kapag kailangan ng mas detalyadong paliwanag. Inilalarawan nang tiyak ang pag-andar ng function, mga argumento, at return value, at gumagamit ng mga bagong linya upang mapabuti ang nababasa.
def add(a, b):
    """
    Nagdadagdag ng dalawang numero at ibinabalik ang resulta.

    Mga argumento:
        a (int): Ang unang numerong idaragdag
        b (int): Ang ikalawang numerong idaragdag

    Pinagbalik:
        int: Ang kabuuan ng dalawang numero
    """
    return a + b

3. Mga estilo ng docstring (Google style, NumPy style, reStructuredText style)

docstring na estilo ay may iba’t ibang anyo depende sa proyekto at mga tool na ginagamit. Pangunahing tatlong estilo—Google style, NumPy style, at reStructuredText style—ang malawakang ginagamit.

Google style

Ang Google style ay kilala sa maikli at biswal na madaling maintindihang pagsulat. Ang mga argumento at return value ay inilalagay sa ilalim ng mga seksyong tinatawag na Args at Returns, na idinisenyo upang madaling maunawaan ang paglalarawan ng mga Python function.
def add(a, b):
    """
    Idinadagdag ang dalawang numero at ibinabalik ang resulta.

    Args:
        a (int): Ang unang numero na idaragdag
        b (int): Ang ikalawang numero na idaragdag

    Returns:
        int: Ang kabuuan ng dalawang numero
    """
    return a + b

NumPy style

Ang NumPy style ay isang format na nagbibigay ng mas detalyadong paliwanag, at malawakang ginagamit sa dokumentasyon ng mga library na ginagamit sa siyentipikong kalkulasyon at data analysis. Gumagamit ito ng mga seksyong tulad ng Parameters at Returns upang ilarawan nang detalyado ang mga argumento at return value.
def add(a, b):
    """
    Idinadagdag ang dalawang numero at ibinabalik ang resulta.

    Parameters
    ----------
    a : int
        Ang unang numero na idaragdag
    b : int
        Ang ikalawang numero na idaragdag

    Returns
    -------
    int
        Ang kabuuan ng dalawang numero
    """
    return a + b

reStructuredText style

Ang reStructuredText style ay format na ginagamit ng dokumentong generator na Sphinx, at karaniwang ginagamit sa mga komplikadong proyekto. Ginagamit ng Sphinx ang estilo na ito upang awtomatikong lumikha ng mga dokumento sa format na HTML o PDF mula sa code.
def add(a, b):
    """
    Idinadagdag ang dalawang numero.

    :param a: Ang unang numero na idaragdag
    :type a: int
    :param b: Ang ikalawang numero na idaragdag
    :type b: int
    :return: Ang kabuuan ng dalawang numero
    :rtype: int
    """
    return a + b

4. PEP 257 at Pinakamahusay na Kasanayan

Sa opisyal na gabay sa estilo para sa docstring ng Python na tinatawag na PEP 257, ibinibigay ang malinaw na mga patnubay kung paano sumulat ng docstring. Sa pagsunod dito, tataas ang nababasa ng code, at mas madali itong mauunawaan ng ibang mga developer pati na rin ng sarili mo.

Mahahalagang Punto ng PEP 257

  1. Isang-linyang docstring Inirerekomenda na para sa mga simpleng function o method, magsulat ng maikling paglalarawan sa isang linya.
  2. Maramihang-linyang docstring Kapag kailangan ng mas detadong paliwanag, gumamit ng maramihang-linyang docstring. Sa ganitong kaso, ang unang linya ay dapat maging simpleng buod, sinusundan ng isang blangkong linya bago ilahad ang detalyadong paliwanag.
  3. Paggamit ng Indentasyon at Blangkong Linya Sa loob ng docstring, gumamit ng mga pagbalik ng linya at indentasyon upang mapabuti ang nababasa. Bukod dito, ang impormasyon tungkol sa mga argumento at return value ng function ay dapat malinaw na hatiin upang maging mas madaling basahin at organisado.

Pinakamahusay na Kasanayan

  • Maikli at Malinaw na Paliwanag Ang docstring ay dapat maikli ngunit eksaktong magpahayag kung ano ang ginagawa ng function o klase. Alisin ang hindi kailangang impormasyon habang detalyado ang mahalagang bahagi.
  • Pagpapanatili ng Konsistent na Estilo Sa pamamagitan ng pag-iisa ng estilo ng docstring sa buong proyekto, tataas ang nababasa. Pumili ng estilo na angkop sa iyong koponan o proyekto, tulad ng Google style o NumPy style.
RUNTEQ（ランテック）｜超実戦型エンジニア育成スクール

5. Pagsusuri gamit ang docstring (doctest)

Pythonには、docstring内のサンプルコードが実際に期待通りの動作をするかどうかをテストする機能として、doctestモジュールがあります。この機能を使用することで、docstringに記述されたコード例が正しいかを自動的に確認でき、コードの信頼性を向上させることができます。doctestを活用すれば、ドキュメント化されたコードのテストを手軽に行うことが可能です。

Pangunahing paraan ng paggamit ng doctest

doctestは、docstring内のサンプルコードを自動的に検出し、その結果が記述された通りの出力を返すかどうかを確認します。次のように、if __name__ == "__main__":ブロックにdoctestを追加することで、テストを実行できます。
def add(a, b):
    """
    Nagbabalik ng kabuuan ng dalawang numero.

    Args:
        a (int): unang numero
        b (int): ikalawang numero

    Returns:
        int: suma ng dalawang numero

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()
上記の例では、doctestがdocstring内のコードサンプルを実行し、その結果を比較します。テストが成功した場合、何も表示されませんが、失敗した場合にはエラーメッセージが表示されます。これにより、docstring内のサンプルコードが常に正しいことを保証できます。

Mga benepisyo ng paggamit ng doctest

  1. Pagkakaugnay ng code doctestを使用することで、docstring内に記述されたサンプルコードが実際に動作するかどうかを確認でき、コードとドキュメントの一貫性を保つことができます。これにより、ドキュメントが最新のコードと常に一致する状態が保たれます。
  2. Pag-automate ng pagsusuri doctestは簡単に自動化でき、関数やクラスのテストを手動で行う必要がありません。doctestを実行するだけで、docstring内の全てのコード例がテストされるため、ミスを減らすことができます。

6. Praktikal na Halimbawa: Pagdodokumento ng Code gamit ang docstring

Sa pamamagitan ng aktwal na paggamit ng docstring, ang Python code ay nagiging mas nababasa nang malaki, at mas madaling maunawaan ng ibang mga developer. Dito, ipapakita namin ang proseso ng pagdaragdag ng angkop na docstring sa mga klase at function, at paggamit ng Sphinx upang awtomatikong i-dokumento ito.

Halimbawa ng Pagsusulat ng docstring para sa Klase

Inirerekomenda rin na magsulat ng docstring para sa mga klase at method. Ang docstring para sa klase ay nagbibigay ng maikling paglalarawan kung anong mga tampok ang inaalok ng klase, at ang docstring para sa bawat method ay detalyadong naglalarawan ng mga tiyak na tampok.
class Calculator:
    """
    Simpleng calculator class.

    Ang klase na ito ay nagsasagawa ng mga pangunahing pagdaragdag, pagbabawas, pag-multiply, at pag-divide.

    Attributes:
        result (int): Variable na nag-iimbak ng resulta ng kalkulasyon
    """

    def __init__(self):
        """
        Constructor ng Calculator class.
        Sa pag-initialize, ang resulta ay itinatakda sa 0.
        """
        self.result = 0

    def add(self, a, b):
        """
        Nagdadagdag ng dalawang numero at ibinabalik ang resulta.

        Args:
            a (int): Unang numero
            b (int): Ikalawang numero

        Returns:
            int: Ang kabuuan ng dalawang numero
        """
        self.result = a + b
        return self.result
Sa halimbawang ito ng klase, kasama ang pangkalahatang paglalarawan ng klase, may hiwalay na docstring din para sa mga method na __init__ at add. Sa ganitong paraan, madaling mauunawaan ng mga gumagamit ng klase kung paano gumagana ang bawat method.

Pagbuo ng Dokumentasyon gamit ang Sphinx

Sa paggamit ng Sphinx, maaaring awtomatikong lumikha ng dokumentong HTML o PDF batay sa docstring. Una, i-integrate ang Sphinx sa proyekto at ihanda ang configuration file (conf.py). Pagkatapos, sa pamamagitan ng pagtakbo ng utos make html, awtomatikong mabubuo ang HTML na dokumento mula sa docstring. I-install ang Sphinx gamit ang sumusunod na utos:
pip install sphinx
Pagkatapos, gamitin ang utos sphinx-quickstart upang i-inisyalisa ang proyekto at i-configure ito ayon sa pangangailangan. Pagkatapos nito, awtomatikong mabubuo ang dokumentong naglalaman ng mga docstring na nakasulat sa mga Python file.

7. Karaniwang mga pagkakamali at kung paano iwasan ang mga ito

docstring kapag sinusulat, may mga pagkakamaling madalas magawa ng mga baguhan. Sa seksyong ito, tatalakayin ang mga karaniwang pagkakamali at kung paano ito iwasan.

1. Malabong paliwanag

docstring ay kailangang isulat nang malinaw at maikli, ngunit sa malabong paliwanag ay hindi naipapahayag ang layunin sa mambabasa. Halimbawa, ang sumusunod na docstring ay hindi sapat.
def add(a, b):
    """Idinadagdag ang dalawang numero."""
    return a + b
Sa halimbawang ito, kulang ang paliwanag tungkol sa mga argumento at return value, kaya hindi malinaw kung anong uri ng data ang tinatanggap at kung ano ang ibinabalik. Bilang solusyon, isusulat ito ng ganito.
def add(a, b):
    """
    Idinadagdag ang dalawang integer at ibinabalik ang resulta.

    Args:
        a (int): Unang numero
        b (int): Ikalawang numero

    Returns:
        int: Ang kabuuan ng dalawang numero
    """
    return a + b

2. Hindi tumpak na paglalarawan ng mga argumento at return value

docstring sa loob, kung walang detalyadong paliwanag tungkol sa mga argumento at return value, hindi magagamit ng tama ng mga gumagamit ang function. Lalo na kapag komplikado ang function, mahalagang ilahad nang malinaw ang uri at kahulugan ng mga argumento pati na rin ang uri ng return value.
def divide(a, b):
    """Hinahati ang dalawang numero."""
    return a / b
Sa halimbawang ito, kulang ang paliwanag tungkol sa mga argumento at paghawak ng error. Sa pamamagitan ng pagsulat tulad ng sumusunod, mauunawaan ng mga gumagamit nang tama kung paano gamitin ang function.
def divide(a, b):
    """
    Hinahati ang dalawang numero at ibinabalik ang resulta. Kapag hinati sa zero, magtataas ng ZeroDivisionError.

    Args:
        a (float): Ang numerong hahatiin
        b (float): Ang divisor

    Returns:
        float: Resulta ng paghahati

    Raises:
        ZeroDivisionError: Kapag sinubukang hatiin sa zero
    """
    if b == 0:
        raise ZeroDivisionError("Hindi maaaring hatiin sa zero")
    return a / b
Sa ganitong paraan, mahalagang maglagay ng sapat na impormasyon sa docstring upang magamit ng mga gumagamit ang code nang walang pagkalito.

8. Buod: Paggamit ng docstring para sa epektibong paglikha ng dokumentasyon

Sa artikulong ito, tinalakay namin ang kahalagahan ng docstring sa Python, pati na ang paraan ng pagsulat nito, estilo, at mga best practice. Ang docstring ay napakahalaga para mapabuti ang nababasa at maintainability ng code, at sa pagsunod sa mga alituntunin ng PEP 257, makakalikha ng magkakaugnay na dokumentasyon. Dagdag pa rito, natutunan din namin kung paano gamitin ang doctest para sa pagsusuri at ang Sphinx para sa pagbuo ng dokumentasyon, upang magamit ang docstring. Dahil dito, inaasahang tataas ang kalidad ng code at kahusayan sa pag-develop.

Paglikha ng magkakaugnay na dokumentasyon batay sa PEP 257

Ang PEP 257 ay opisyal na gabay para sa pagsulat ng docstring sa Python, at sa pagsunod dito, makakalikha ng magkakaugnay at madaling basahin na dokumentasyon. Lalo na, sa pamamagitan ng paggamit ng simpleng isang-linyang docstring at ng maraming-linyang docstring na may detalyadong paliwanag, maipapahayag nang tama ang layunin ng code.

Pagsusuri ng sample code gamit ang doctest

Sa pamamagitan ng paggamit ng doctest, awtomatikong masusubok ang mga sample code na nakasulat sa docstring. Sa ganitong paraan, mapapanatili ang pagkakatugma ng code at dokumentasyon habang napipigilan ang mga bug at pagkakamali.

Awtonomatikong pagbuo ng dokumentasyon gamit ang Sphinx

Kung gagamitin ang mga tool tulad ng Sphinx para sa pagbuo ng dokumentasyon, awtomatikong makakalikha ng mga dokumentong HTML o PDF mula sa docstring. Sa ganitong paraan, nababawasan ang abala ng manu-manong paggawa ng dokumentasyon at palaging maibibigay ang pinakabagong dokumento batay sa kasalukuyang code.
侍エンジニア塾