docstring
Főnév
docstring (tsz. docstrings)
- (informatika) A Python nyelv egyik kiváló tulajdonsága az, hogy támogatja a beágyazott dokumentációt, amit docstring-nek (documentation string) nevezünk.
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.
📌 Miért fontos a docstring?
✅ 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
📌 Alapszintaxis
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.
📌 Egyszerű példa
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.
📌 Docstring különböző helyeken
A docstring nemcsak függvényekhez, hanem modulokhoz, osztályokhoz, metódusokhoz és csomagokhoz is használható.
Modul docstring
Minden .py fájl tetején elhelyezhetsz egy docstringet:
"""
Ez a modul különféle matematikai műveletekhez tartalmaz segédfüggvényeket.
"""
Osztály docstring
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
Metódus docstring
class Person:
def greet(self):
"""
Kiír egy személyes üdvözlő üzenetet.
"""
print(f"Hello, my name is {self.name}!")
📌 Formátumok
Nincs kötelező formátum, de a közösségben elfogadottak a következők:
1️⃣ Egyszerű stílus
Rövid, 1 soros leírás:
def add(a, b):
"""Összead két számot és visszaadja az eredményt."""
return a + b
2️⃣ Többsoros stílus
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
📌 Legnépszerűbb docstring stílusok
👉 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
📌 Hogyan jelenik meg a docstring?
Az interpreterből, shellből vagy Jupyter notebookban:
help(greet)
Ekkor a Python kiírja a docstring tartalmát.
Vagy:
print(greet.__doc__)
📌 Best practice — Jó gyakorlat
✅ 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
📌 Miért fontos a docstring hosszú távon?
- Ha csapatban dolgozol, a többiek is tudják, mit csinál a függvényed.
- Ha hónapok múlva visszatérsz a kódhoz, nem kell újból kibogozni, mit akartál vele.
- Automatizált API dokumentáció generálható belőle (Sphinx, pdoc, pdoc3, mkdocs).
- IDE-k kiolvassák és mutatják autocomplete közben.
- Professzionális Python kódban (pl. GitHub libek) elvárt a docstring.
📌 Speciális esetek
- Private függvényekhez (pl.
_helper_func) is lehet írni docstringet, de nem kötelező. - Dunder metódusokhoz (
__init__,__str__, stb.) szintén érdemes.
📌 Docstring automatikus ellenőrzése
Lint eszközök:
pydocstyle(PEP 257 compliance)flake8-docstrings- Integrálható CI pipeline-ba (GitHub Actions, GitLab CI)
📌 Összefoglalás
✅ 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)