docstring (tsz. docstrings)
A docstring egy speciális karakterlánc (string), amelyet közvetlenül egy modul, osztály, függvény vagy metódus definíciója után helyezünk el. Célja, hogy leírja, mire szolgál az adott elem, hogyan kell használni, milyen paramétereket vár, és mit ad vissza.
A docstring a Python hivatalos dokumentációs módszere.
✅ Javítja a kód olvashatóságát ✅ Segít másoknak (és magadnak is) megérteni a kódot később ✅ Megkönnyíti az automatikus dokumentáció generálást (pl. Sphinx, pydoc) ✅ IDE-k (pl. PyCharm, VSCode) a docstring segítségével adnak tooltipet, autocomplete infót ✅ Jó gyakorlat a professzionális Python kódban
A docstring egy többsoros string, amit általában három idézőjel-pár (""" """ vagy ) közé írunk.
Elhelyezése:
def function_name(parameters):
"""
Ez a docstring.
Leírja, hogy mire való ez a függvény.
"""
# function body
A Python interpreter automatikusan eltárolja a docstringet az adott elem __doc__ attribútumában.
def greet(name):
"""
Kiír egy üdvözlő üzenetet a megadott névhez.
Paraméterek:
name (str): A felhasználó neve.
Nincs visszatérési érték.
"""
print(f"Hello, {name}!")
Ha megnézed a __doc__ attribútumot:
print(greet.__doc__)
Kimenet:
Kiír egy üdvözlő üzenetet a megadott névhez. Paraméterek: name (str): A felhasználó neve. Nincs visszatérési érték.
A docstring nemcsak függvényekhez, hanem modulokhoz, osztályokhoz, metódusokhoz és csomagokhoz is használható.
Minden .py fájl tetején elhelyezhetsz egy docstringet:
"""
Ez a modul különféle matematikai műveletekhez tartalmaz segédfüggvényeket.
"""
class Person:
"""
Egy ember osztály.
Attribútumok:
name (str): Az ember neve.
age (int): Az életkor.
"""
def __init__(self, name, age):
self.name = name
self.age = age
class Person:
def greet(self):
"""
Kiír egy személyes üdvözlő üzenetet.
"""
print(f"Hello, my name is {self.name}!")
Nincs kötelező formátum, de a közösségben elfogadottak a következők:
Rövid, 1 soros leírás:
def add(a, b):
"""Összead két számot és visszaadja az eredményt."""
return a + b
def add(a, b):
"""
Összead két számot.
Paraméterek:
a (int, float): Első szám.
b (int, float): Második szám.
Visszatérési érték:
int vagy float: Az összeadás eredménye.
"""
return a + b
👉 PEP 257 ajánlás a hivatalos stílusról.
👉 Google stílusú docstring (széles körben használt):
def multiply(a, b):
"""
Multiply two numbers.
Args:
a (int): First number.
b (int): Second number.
Returns:
int: The result of multiplication.
"""
return a * b
👉 NumPy/SciPy stílus:
def divide(a, b):
"""
Divide two numbers.
Parameters
----------
a : int or float
Numerator.
b : int or float
Denominator.
Returns
-------
float
The division result.
"""
return a / b
👉 reStructuredText stílus (Sphinx dokumentációhoz):
def subtract(a, b):
"""
Subtract two numbers.
:param a: First number.
:type a: int
:param b: Second number.
:type b: int
:return: Result of subtraction.
:rtype: int
"""
return a - b
Az interpreterből, shellből vagy Jupyter notebookban:
help(greet)
Ekkor a Python kiírja a docstring tartalmát.
Vagy:
print(greet.__doc__)
✅ Mindig írjunk docstringet publikus függvényekhez, osztályokhoz, modulokhoz ✅ Tömör, világos nyelvezetet használjunk ✅ Az első sor legyen rövid összefoglalás ✅ Ha bővebb leírás kell, legyen egy üres sor utána, majd részletes leírás ✅ Dokumentáljuk a paramétereket, visszatérési értéket, kivételeket is ✅ Ha a függvény “void” (nem ad vissza semmit), ezt is írjuk le
_helper_func) is lehet írni docstringet, de nem kötelező.__init__, __str__, stb.) szintén érdemes.
Lint eszközök:
pydocstyle (PEP 257 compliance)flake8-docstrings
✅ A docstring a Python hivatalos beágyazott dokumentációs módszere ✅ Függvény, osztály, modul, metódus első sora után helyezkedik el ✅ Három idézőjel közé írt string ✅ Az IDE és a help() függvény is kiolvassa ✅ Többféle stílusban írható (Google, NumPy, reST) ✅ Nagyon fontos a professzionális, tiszta kódhoz ✅ Könnyű automatizált dokumentáció generálásához
Ha szeretnéd, szívesen adok konkrét példákat is a következőkre:
✅ teljes modulos docstring ✅ osztály + metódus docstring kombináció ✅ __init__, __str__ docstring ✅ hibakezelés dokumentálása (Raises szakasz)