Python - Docstrings (Italiano)

Ciao, aspiranti programmatori Python! Oggi, esploreremo il meraviglioso mondo delle docstrings. Come il tuo insegnante di informatica amichevole del quartiere, sono entusiasta di guidarti attraverso questo aspetto essenziale della programmazione in Python. Quindi, prendi la tua bevanda preferita, metti te stesso a tuo agio e iniziamo questa avventura di apprendimento insieme!

Docstrings in Python

Immagina di scrivere un diario. All'inizio di ogni voce, potresti annotare un breve riassunto di ciò che è successo quel giorno. Beh, le docstrings in Python sono un po' così! Sono stringhe speciali che descrivono cosa fa un pezzo di codice, rendendo più facile per te (e per gli altri) capire il tuo codice in seguito.

In Python, le docstrings sono racchiuse tra triple virgolette (""" o ''') e sono posizionate subito dopo la definizione di una funzione, classe o modulo. Vediamo un semplice esempio:

def saluta(nome):
"""Questa funzione saluta la persona passata come parametro"""
print(f"Ciao, {nome}!")

In questo esempio, la riga tra le triple virgolette è la nostra docstring. Spiega brevemente cosa fa la funzione saluta.

Docstrings a Linea Singola

Per funzioni o classi semplici, una docstring a linea singola potrebbe essere tutto ciò di cui hai bisogno. Ecco un altro esempio:

def quadrato(n):
"""Restituisce il quadrato di un numero."""
return n ** 2

Questa docstring è breve e dolce, dicendoci esattamente cosa fa la funzione in una sola riga.

Docstrings a Più Linee

Per funzioni o classi più complesse, potresti aver bisogno di una docstring a più linee. Queste tipicamente includono una riga di sommario, seguita da una riga vuota e poi informazioni più dettagliate. Vediamo un esempio:

def calcola_area(lunghezza, larghezza):
"""
Calcola l'area di un rettangolo.

Parametri:
lunghezza (float): La lunghezza del rettangolo
larghezza (float): La larghezza del rettangolo

Restituisce:
float: L'area del rettangolo
"""
return lunghezza * larghezza

Questa docstring a più linee fornisce informazioni più dettagliate sui parametri della funzione e su ciò che restituisce.

Docstrings per Moduli

Anche i moduli possono avere docstrings! Queste sono posizionate all'inizio del file. Per esempio:

"""
Questo modulo contiene funzioni di utilità per calcoli geometrici.
Include funzioni per calcolare aree e volumi di varie forme.
"""

def calcola_area_cerchio(raggio):
# Implementazione della funzione qui

Docstrings per Classi

Le classi possono anche avere docstrings. Queste sono posizionate subito dopo la definizione della classe:

class Rettangolo:
"""
Una classe per rappresentare un rettangolo.

Attributi:
lunghezza (float): La lunghezza del rettangolo
larghezza (float): La larghezza del rettangolo
"""

def __init__(self, lunghezza, larghezza):
self.lunghezza = lunghezza
self.larghezza = larghezza

Accesso alle Docstrings

Una delle cose cool delle docstrings è che puoi accedervi programmaticamente. Python memorizza la docstring come attributo __doc__ della funzione, classe o modulo. Ecco come puoi accedervi:

def saluta(nome):
"""Questa funzione saluta la persona passata come parametro"""
print(f"Ciao, {nome}!")

print(saluta.__doc__)

Questo restituirà: Questa funzione saluta la persona passata come parametro

Best Practices per Scrivere Docstrings

Ora che sappiamo come scrivere docstrings, parliamo di alcune best practices:

1. Mantienila concisa ma informativa
2. Usa una grammatica e una punteggiatura corrette
3. Sii coerente nel tuo stile
4. Include informazioni sui parametri e sui valori restituiti delle funzioni
5. Per le classi, descrivi attributi e metodi importanti

Stile di Docstring di Google

Google ha la sua guida di stile per le docstrings. Ecco un esempio:

def divide(a, b):
"""Dividi due numeri.

Args:
a (int): Il numeratore.
b (int): Il denominatore.

Returns:
float: Il risultato della divisione.

Raises:
ZeroDivisionError: Se b è 0.
"""
if b == 0:
raise ZeroDivisionError("Non si può dividere per zero")
return a / b

Stile di Docstring NumPy/SciPy

Se stai lavorando con librerie scientifiche Python, potresti incontrare lo stile NumPy/SciPy:

def calcola_media(numeri):
"""
Calcola la media aritmetica di una lista di numeri.

Parametri
----------
numeri : list
Una lista di numeri.

Restituisce
-------
float
La media aritmetica dell'elenco di input.
"""
return sum(numeri) / len(numeri)

Stile di Docstring di Sphinx

Sphinx è un popolare generatore di documentazione per Python. Il suo stile è simile al formato reStructuredText:

def fibonacci(n):
"""
Genera una sequenza di Fibonacci fino a n.

:param n: Il numero di numeri di Fibonacci da generare
:type n: int
:return: Una lista di numeri di Fibonacci
:rtype: list
"""
sequenza = [0, 1]
while len(sequenza) < n:
sequenza.append(sequenza[-1] + sequenza[-2])
return sequenza[:n]

Docstring vs Commento

Potresti te stesso chiedere, "Qual è la differenza tra una docstring e un commento normale?" Grande domanda! Analizziamola:

1. Sintassi: Le docstrings usano triple virgolette, mentre i commenti usano #.
2. Posizionamento: Le docstrings vengono subito dopo una definizione, mentre i commenti possono andare ovunque.
3. Scopo: Le docstrings spiegano cosa fa il codice, i commenti spiegano come lo fa.
4. Accessibilità: Le docstrings possono essere accessibili programmaticamente, i commenti no.

Ecco un esempio rapido per illustrare:

def aggiungi(a, b):
"""
Aggiunge due numeri e restituisce il risultato.
"""
# Questo è un commento che spiega come facciamo l'addizione
return a + b  # Questo è un commento in linea

E eccoci qui, ragazzi! Abbiamo coperto i pro e contro delle docstrings in Python. Ricorda, una buona documentazione è come lasciare una scia di biscotti per il futuro te stesso (o altri sviluppatori) da seguire. Potrebbe sembrare lavoro in più ora, ma ti ringrazio io stesso più tardi!

Ecco una tabella di riferimento rapida degli stili di docstring che abbiamo coperto:

Stile	Sommario	Esempio
A Linea Singola	Breve descrizione a linea singola	"""Restituisce il quadrato di un numero."""
A Più Linee	Descrizione dettagliata con parametri e valore restituito	"""Calcola l'area di un rettangolo.\n\nParametri:\n..."""
Google	Include Args, Returns e Raises sezioni	"""Dividi due numeri.\n\nArgs:\n..."""
NumPy/SciPy	Usa Parameters e Returns sezioni con formattazione più dettagliata	"""Calcola la media aritmetica di una lista di numeri.\n\nParameters\n----------\n..."""
Sphinx	Usa :param:, :type:, :return: e :rtype: campi	"""Genera una sequenza di Fibonacci fino a n.\n\n:param n: ..."""

Buon coding, e che le tue docstrings siano sempre chiare e informative!

Credits: Image by storyset