El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència

HOME

Tancàvem el mòdul 7 amb un diagnòstic incòmode: TascaFàcil v0.17 funciona, està ben repartit en mòduls i no té ni un sol cicle d'importació, però no està documentat més enllà d'unes quantes docstrings soltes. Si demà la Marta contracta algú i li passa la carpeta tascafacil/, aquesta persona haurà de llegir-se els cinc fitxers sencers per esbrinar què fa el programa, com s'engega i què significa que una tasca tingui dies. I no cal imaginar-se un desconegut: tu d'aquí a sis mesos ets exactament aquest desconegut, amb el desavantatge afegit de creure't que te'n recordes. Aquesta lliçó converteix el paquet en una cosa que s'entén en cinc minuts: comentaris que expliquen el perquè i no el què, docstrings de debò seguint la convenció oficial, anotacions de tipus que documenten i a més ajuden l'editor, i un README.md que és la porta d'entrada del projecte. Documentar no és escriure molt: és escriure allò que el codi no pot dir per si sol.

Contingut

Per a qui es documenta
Comentaris: la regla d'or
Comentaris que menteixen i marcadors TODO/FIXME
Docstrings: la convenció PEP 257
Els tres estils: Google, NumPy i reStructuredText
Anotacions de tipus: documentació executable
El README.md del projecte
CHANGELOG.md, versionatge semàntic i eines
TascaFàcil v0.18: el paquet documentat
Errors habituals i consells
Exercicis
Conclusió

Per a qui es documenta

Abans d'escriure ni una sola línia convé tenir clar a qui l'escrius, perquè cada lector necessita coses diferents:

Lector	Què necessita saber	On ho busca
Qui fa servir el programa	Què fa, com s'instal·la, com s'engega	`README.md`
Qui fa servir una funció teva	Què rep, què retorna, què pot fallar	Docstring i anotacions
Qui modifica el codi	Per què està fet així i no d'una altra manera	Comentaris al punt exacte
Tu d'aquí a sis mesos	Tot l'anterior, i ho has oblidat	Els tres llocs alhora

D'aquí surten les tres eines de la lliçó, i cadascuna té el seu lloc: el README explica el projecte des de fora, les docstrings expliquen cada peça a qui la farà servir, i els comentaris expliquen decisions concretes a qui tocarà aquella línia. Confondre-les és el primer error: un README de dues-centes línies no substitueix una docstring, i un comentari dins d'una funció no el llegirà mai qui només la vol cridar. I un advertiment que travessa tota la lliçó: la millor documentació és el codi que no la necessita; abans d'escriure un comentari que expliqui un tram confús, pregunta't si no seria millor reanomenar una variable o extreure una funció amb un nom clar, cosa que reprendrem a Estil, llegibilitat i refactorització.

Comentaris: la regla d'or

La sintaxi ja la coneixes des del mòdul 2: # converteix en comentari tot el que va des d'aquell punt fins al final de la línia, i Python ho ignora completament. Pot ocupar una línia sencera o anar al final d'una línia de codi. El que no és evident és què escriure-hi a dins, i aquí la regla d'or és aquesta: el codi diu el què; el comentari diu el perquè. L'intèrpret ja explica amb total precisió el que passa; el que no pot explicar és la decisió, la restricció o la sorpresa que hi ha al darrere.

# COMENTARIS INUTILS: repeteixen el que el codi ja diu
comptador = comptador + 1                # incrementem el comptador en un
if tasca.completada:                     # si la tasca esta completada
    fetes.append(tasca)                  # l afegim a la llista de fetes
# COMENTARI VALUOS: explica el perque
# L equip treballa de dilluns a divendres: 5 dies reals per setmana natural.
# Sense aquest ajust, una tasca de 10 dies queia en dissabte a l informe de la Marta.
setmanes = dies / 5

Els tres primers comentaris no aporten res: qualsevol que sàpiga Python els dedueix llegint la línia, i a més envelleixen malament. L'últim conté informació que no és enlloc del codi: una regla de negoci de l'Estudi Alba que va costar una tarda de descobrir. Si l'esborres, aquesta informació desapareix de l'univers. Casos en què un comentari gairebé sempre val la pena:

Regles de negoci que un lector no pot endevinar (els 5 dies laborables, el descompte del client Vidal) i decisions descartades: «es va fer servir cerca lineal expressament: la llista mai no passa de 200 tasques».
Trucs obligats per una limitació externa: un format de fitxer estrany, una peculiaritat d'una biblioteca.
Advertiments, fórmules i unitats: «no canviïs l'ordre d'aquestes dues línies», o d'on surt un número i en quina unitat està.

Comentaris que menteixen i marcadors `TODO`/`FIXME`

Hi ha una cosa pitjor que la manca d'un comentari: un comentari que menteix. El codi es canvia i el comentari es queda com estava, i a partir d'aquí enganya activament qui el llegeixi.

# Retorna les tasques de prioritat alta      <-- MENTIDA: ja no filtra per prioritat
def pendents(agenda):
    return [t for t in agenda if not t.completada]

Qui llegeixi aquest comentari hi confiarà i buscarà l'error en un altre lloc. La disciplina és simple i no negociable: quan canvies una línia, en revises el comentari; i entre un comentari dubtós i cap, cap és millor. Aquest risc és un altre argument a favor de les anotacions de tipus i dels bons noms: no es desincronitzen tan fàcilment perquè formen part del codi. Per a les tasques pendents, a més, existeix una convenció universal que tots els editors reconeixen i ressalten:

Marcador	Significat	Exemple
`TODO`	Falta fer alguna cosa, però no està trencat	`# TODO: permetre editar el responsable`
`FIXME`	Hi ha alguna cosa malament que caldrà arreglar	`# FIXME: si dies es 0 la mitjana peta`
`HACK`	Solució provisional i lletja, a consciència	`# HACK: reordenem dues vegades per un error de l export`
`NOTE`	Avís important per a qui llegeixi	`# NOTE: aquest fitxer el llegeix l script de la Marta`

A VS Code apareixen ressaltats i es poden llistar tots amb una cerca de TODO al projecte. Escriu-los amb una frase concreta —# TODO: validar el correu serveix; # TODO: millorar això no— i revisa'ls de tant en tant: un projecte amb quaranta TODO de fa dos anys és un projecte on ningú no els llegeix.

Docstrings: la convenció PEP 257

Una docstring és una cadena de text col·locada com a primera instrucció d'un mòdul, una classe o una funció. A diferència d'un comentari, Python la desa a l'atribut __doc__ de l'objecte, de manera que es pot consultar en temps d'execució. Les fem servir de passada des de 04-01; ara les farem bé. La convenció oficial és la PEP 257, i les seves regles pràctiques són aquestes:

S'escriuen sempre amb cometes triples ("""), fins i tot si ocupen una sola línia, i la primera és un resum curt en mode imperatiu acabat en punt: «Retorna...», «Calcula...», «Desa...», mai «Aquesta funció retorna...».
Si hi ha més text, es deixa una línia en blanc després del resum, i les cometes de tancament van en la seva pròpia línia.

def dies_restants(tasca):
    """Retorna els dies que falten per acabar la tasca.

    Mai no retorna un numero negatiu: si l equip ha dedicat mes dies
    dels previstos, el resultat es 0.
    """
    return max(0, tasca.dies - tasca.fets)

Les docstrings van en quatre llocs, i cadascuna respon a una pregunta diferent:

On	Què ha d'explicar
Mòdul (primera línia del `.py`)	Què conté el fitxer i per a què serveix
Paquet (al `__init__.py`)	Què és el projecte i quins mòduls el formen
Classe (sota la línia `class`)	Què representa, els seus atributs i el seu ús típic
Funció o mètode (sota el `def`)	Què fa, què rep, què retorna i què pot fallar

I així es llegeixen, sense sortir de l'intèrpret: help(Tasca.completar) mostra la signatura i la docstring ja formatades, Tasca.completar.__doc__ retorna la cadena en cru i help(tascafacil.model) presenta la documentació del mòdul sencer. Aquest és el motiu real d'escriure-les: help() funciona amb el teu codi igual que amb help(str.upper). Si la docstring està ben escrita, qui faci servir el teu mòdul no necessita obrir el fitxer.

Els tres estils: Google, NumPy i reStructuredText

Per a funcions amb diversos paràmetres cal una estructura. Existeixen tres convencions esteses; totes diuen el mateix i canvien només en la forma. Aquí tens la mateixa funció en les tres:

# --- Estil Google: el mes llegible en text pla ---
def filtrar_per(tasques, camp, valor):
    """Retorna les tasques el camp de les quals coincideix amb el valor donat.

    Args:
        tasques (list[Tasca]): Colleccio de tasques a filtrar.
        camp (str): Nom de l atribut, per exemple "responsable".
        valor (str): Valor buscat, sense distingir majuscules.

    Returns:
        list[Tasca]: Les tasques que compleixen la condicio.

    Raises:
        AttributeError: Si el camp no existeix a Tasca.
    """
# --- Estil NumPy: apartats subratllats amb guions ---
    """
    Parameters
    ----------
    tasques : list[Tasca]
        Colleccio de tasques a filtrar.
    camp : str
        Nom de l atribut, per exemple "responsable".

    Returns
    -------
    list[Tasca]
        Les tasques que compleixen la condicio.
    """
# --- Estil reStructuredText (Sphinx classic): camps amb dos punts ---
    """
    :param tasques: Colleccio de tasques a filtrar.
    :returns: Les tasques que compleixen la condicio.
    """

Estil	Aspecte en text pla	Verbositat	On es veu més
Google	Molt llegible tal qual	Baixa	Projectes generals, Python modern
NumPy	Llegible, ocupa més	Mitjana	Ciència de dades: `numpy`, `scipy`, `pandas`
reStructuredText	Sorollós sense renderitzar	Alta	Projectes antics amb Sphinx

Recomanació per a aquest curs: l'estil Google. És el que millor es llegeix sense eines, el més curt i el que menys molesta mentre programes. Però l'important no és quin triïs, sinó ser consistent: un projecte amb tres estils barrejats confon més que un sense documentar. Tria'n un, anota'l al README i respecta'l. Un detall pràctic: amb anotacions de tipus pots estalviar-te els tipus entre parèntesis, perquè ja són a la signatura; camp (str): passa a ser camp:.

Anotacions de tipus: documentació executable

Les anotacions de tipus (type hints) declaren quin tipus s'espera a cada paràmetre i quin tipus es retorna. S'escriuen amb dos punts després del paràmetre i una fletxa -> abans del cos:

def resum(titol: str, dies: int, urgent: bool = False) -> str:
    """Retorna una linia de resum per al llistat."""
    return f"{'!' if urgent else ' '} {titol} ({dies} dies)"

Es llegeix així: titol és un str, dies un int, urgent un bool amb valor per defecte False, i la funció retorna un str. Per a les estructures del mòdul 5 s'indica també què contenen:

Anotació	Significa
`list[str]`	Llista de cadenes
`dict[str, int]`	Diccionari amb claus de text i valors enters
`tuple[str, int]`	Tupla d'exactament dos elements: un text i un enter
`str \| None`	Un text o `None` (típic d'una cerca que pot fallar)
`list[Tasca]`	Llista d'objectes de la teva pròpia classe; `-> None`: no retorna res útil

def cercar(tasques: list[Tasca], titol: str) -> Tasca | None:
    """Retorna la primera tasca amb aquest titol, o None si no existeix."""

El Tasca | None de cercar és especialment valuós: avisa el lector que ha de comprovar el None abans de fer servir el resultat, un avís que sense anotació només seria al cap de qui va escriure la funció. I ara l'imprescindible: Python no comprova les anotacions en execució. La crida resum(titol=42, dies="tres") no llança cap error per les anotacions; el programa continua endavant fins que es trenca més endins, amb un missatge que ja no assenyala el culpable. Les anotacions són documentació que l'editor entén: VS Code autocompleta els mètodes i subratlla l'error abans d'executar. Si vols comprovació real existeix mypy, una eina externa que analitza el codi i avisa de les incoherències (pip install mypy, després mypy tascafacil/). La reprendrem a 08-05 amb la resta d'eines de qualitat.

El `README.md` del projecte

El README.md es col·loca a l'arrel del projecte i és el primer que qualsevol obre (GitHub i GitLab el mostren automàticament, com veurem a 08-03). Ha de respondre, en aquest ordre, a: què és això, què necessito, com ho instal·lo, com ho faig servir, com està organitzat i què hi puc fer. L'essencial de Markdown cap en una taula:

Sintaxi	Resultat
`# Titol` / `## Apartat`	Encapçalaments de nivell 1 i 2
`negreta` / `cursiva` i `- element` / `1. element`	Èmfasi i llistes
`codi` i blocs amb ```	Codi en línia i en bloc
`[text](url)` i files amb `\|`	Enllaç i taula

I aquest és el README de TascaFàcil:

# TascaFacil

Gestor de tasques de linia d ordres per a l equip de l Estudi Alba. Permet
crear tasques, assignar-les a un responsable, marcar-les com a completades, filtrar-les,
ordenar-les per prioritat i desar-les en un fitxer JSON.

## Requisits

- Python 3.10 o superior (es fa servir `match`/`case` i la sintaxi `str | None`).
- Cap biblioteca externa: tot es biblioteca estandard.

## Installacio i us

python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate python -m tascafacil # des de la carpeta del paquet

Les tasques es desen soles a `tasques.json`. L opcio 9 exporta un `tasques.csv`.

## Estructura

- `model.py`: classes `Tasca` i `TascaRecurrent`.
- `agenda.py`: classe `Agenda`, la colleccio i les seves operacions.
- `magatzem.py`: desar i carregar en JSON, exportar a CSV.
- `interficie.py`: menu i entrada/sortida. `__main__.py`: el `main()`.

## Convencions i llicencia

- Docstrings en estil Google. Prioritats valides: `alta`, `mitjana`, `baixa`.
- Equip: Marta, Luis i Nuria (`EQUIP`). Us intern de l Estudi Alba.

Fixa't en el que no té: no explica com funciona Agenda.ordenades() per dins —això és feina de la docstring— ni explica la història del projecte. Un README es mesura per la rapidesa amb què algú passa d'obrir-lo a tenir el programa funcionant.

`CHANGELOG.md`, versionatge semàntic i eines

Al costat del README sol viure-hi un CHANGELOG.md: la llista de canvis de cada versió, la més recent a dalt. Respon a «què ha canviat des de la versió que jo tenia?» sense llegir tot l'historial. I els números de versió que aquest curs fa servir des del mòdul 3 no són arbitraris: segueixen el versionatge semàntic, MAJOR.MENOR.PEDAÇ.

Part	Quan puja	Exemple a TascaFàcil
MAJOR	Canvi que trenca l'ús anterior	0.x → 1.0: el projecte es considera estable
MENOR	Funcionalitat nova compatible	0.17 → 0.18: s'afegeix la documentació
PEDAÇ	Correcció d'un error, sense canvis d'ús	1.0 → 1.0.1: s'arregla un càlcul

Per convenció, qualsevol versió que comenci per 0 significa «això encara pot canviar de qualsevol manera», que és exactament la situació de TascaFàcil durant tot el curs; al final del mòdul arribarà la v1.0. Una entrada de CHANGELOG és tan simple com aquesta:

## [0.18] - 2026-08-05
### Afegit
- Docstrings de modul, classe i funcio a tot el paquet.
- Anotacions de tipus a les funcions publiques, README.md i CHANGELOG.md.

Tot això són fitxers de text, però es poden explotar automàticament. Python porta pydoc, que llegeix les teves docstrings i les presenta ja formatades: python -m pydoc tascafacil.model les mostra a la terminal, python -m pydoc -w tascafacil.model genera un HTML i python -m pydoc -b obre un navegador amb tot el projecte. És la recompensa immediata d'haver escrit docstrings correctes: sense instal·lar res, tens el teu paquet documentat i navegable. Per a projectes grans existeixen Sphinx (el generador amb què està feta la documentació oficial de Python) i MkDocs (més senzill, parteix de fitxers Markdown), que produeixen llocs web complets amb cerca i índex; queden lluny del que TascaFàcil necessita, però s'alimenten de les mateixes docstrings que acabes d'aprendre a escriure.

TascaFàcil v0.18: el paquet documentat

Apliquem-ho tot al projecte: docstring de mòdul a cada fitxer, docstrings completes a les classes, anotacions a les funcions públiques i el README que ja has vist.

"""Model de dades de TascaFacil.

Defineix la classe Tasca i la seva especialitzacio TascaRecurrent, juntament amb les
constants del domini. No depen de cap altre modul del paquet i no
imprimeix res: es pot reutilitzar des d una web o des d un script.
"""


class Tasca:
    """Una tasca de l Estudi Alba amb el seu responsable i la seva estimacio.

    Attributes:
        titol: Descripcio breu, per exemple "Cartell fira del llibre".
        responsable: Nom en minuscules, un dels d EQUIP.
        prioritat: Una de PRIORITATS ("alta", "mitjana" o "baixa").
        dies: Dies estimats de feina; sempre mes gran que 0.
        fets: Dies ja dedicats.
        completada: True si la tasca esta acabada.
    """

    def __init__(self, titol: str, responsable: str, prioritat: str = "mitjana",
                 dies: int = 1) -> None:
        """Crea una tasca normalitzant el responsable i la prioritat."""

    def progres(self) -> float:
        """Retorna el percentatge d avanc, entre 0.0 i 100.0."""
        # dies sempre es > 0 per validacio, aixi que no hi ha divisio per zero
        return min(100.0, self.fets / self.dies * 100)

A agenda.py la docstring de classe inclou a més un exemple d'ús, que és el que més agraeix qui arriba nou; i el __init__.py documenta el paquet sencer i porta el número de versió:

class Agenda:
    """Conjunt de tasques de l equip, amb cerca, filtratge i ordre.

    La llista interna es privada: s hi accedeix recorrent l agenda
    (`for tasca in agenda`) o mitjancant els metodes publics.

    Example:
        >>> agenda = Agenda()
        >>> agenda.afegir(Tasca("Logotip Sole", "nuria", "alta", 5))
        >>> len(agenda)
        1
    """


# --- tascafacil/__init__.py: la docstring de paquet ---
"""TascaFacil: gestor de tasques de l Estudi Alba.

Moduls: model (Tasca i TascaRecurrent), agenda, magatzem i interficie.
Us: python -m tascafacil
"""
__version__ = "0.18"

Ara python -m pydoc -b obre una pàgina amb tot el paquet explicat, i qui rebi la carpeta sap en cinc minuts què és, com s'engega i què fa cada fitxer. TascaFàcil v0.18: mateix comportament, projecte comprensible.

Errors Habituals i Consells

Comentar el què en lloc del perquè, o deixar comentaris que menteixen. comptador += 1 # sumem un és soroll; i en canviar una línia cal revisar-ne el comentari, perquè un de desactualitzat fa més mal que cap.
Fer servir # on toca una docstring. Un comentari a sobre del def no el recullen ni help() ni pydoc; una docstring dins del def, sí.
Docstrings en tercera persona, amb cometes simples o en tres estils barrejats. Cometes triples sempre, primera línia imperativa («Retorna...», no «Aquesta funció retorna...») i un sol estil (Google) anotat al README.
Creure que les anotacions de tipus validen alguna cosa. No ho fan: són documentació; per validar de debò calen comprovacions al codi, o mypy fora d'ell.
Escriure un README que comença per la instal·lació. Comença per una frase que digui què és el programa: hi ha qui només llegirà aquesta línia.
Consell: documenta mentre escrius, no al final. Escriure la docstring abans del cos obliga a aclarir què fa la funció, i de vegades revela que en fa dues i s'hauria de partir.

Exercicis

Exercici 1: Comentaris que aporten

Aquest fragment de l'informe mensual de l'Estudi Alba està ple de comentaris inútils i li falta l'únic que importa. Reescriu-lo deixant només comentaris valuosos i afegeix-hi docstring i anotacions de tipus.

def cost(dies, tarifa):
    total = dies * tarifa          # multipliquem dies per tarifa
    total = total * 1.21           # multipliquem per 1.21
    if dies > 20:                  # si els dies son mes de 20
        total = total * 0.9        # multipliquem per 0.9
    return total                   # retornem el total

Exercici 2: Docstring i anotacions

Escriu la docstring en estil Google i les anotacions de tipus completes d'aquesta funció, incloent-hi l'apartat Raises:

def carregar_equip(ruta):
    with open(ruta, encoding="utf-8") as f:
        return [linia.strip().lower() for linia in f if linia.strip()]

Exercici 3: Versionatge i CHANGELOG

La Marta vol un programa a part, informes, que llegeixi el tasques.json de TascaFàcil. Escriu les dues primeres seccions del seu README.md (què és i requisits) i decideix quin número de versió li correspon a TascaFàcil en cadascun d'aquests tres canvis, justificant-ho: (a) es corregeix un càlcul del progrés que donava 101 %; (b) s'afegeix l'exportació a CSV; (c) Tasca deixa d'acceptar el paràmetre dies i passa a exigir una data de lliurament.

Solucions

Solució 1.

IVA, DESCOMPTE_LLARG, DIES_PROJECTE_LLARG = 1.21, 0.9, 20

def cost(dies: int, tarifa: float) -> float:
    """Retorna el cost d un encarrec amb IVA i descompte per volum.

    Args:
        dies: Dies de feina estimats.
        tarifa: Preu per dia en euros, sense impostos.

    Returns:
        Import final en euros, IVA inclos.
    """
    total = dies * tarifa * IVA
    # L Estudi Alba aplica un 10% de descompte a partir de 20 dies:
    # acordat amb la Marta a la revisio de tarifes del 2026.
    if dies > DIES_PROJECTE_LLARG:
        total *= DESCOMPTE_LLARG
    return round(total, 2)

Han desaparegut els cinc comentaris que repetien el codi i ha aparegut l'únic amb informació real: d'on surt el descompte. Fixa't a més que els números 1.21, 0.9 i 20 s'han convertit en constants amb nom, que es documenten per si soles i eviten haver-les d'explicar (tornarem a aquesta tècnica a 08-05). La docstring explica el que la signatura no diu: que la tarifa va sense impostos i que el resultat els porta.

Solució 2.

def carregar_equip(ruta: str) -> list[str]:
    """Llegeix els noms de l equip d un fitxer de text.

    Cada linia no buida es un nom, retornat sense espais i en minuscules.

    Args:
        ruta: Ruta al fitxer de text, codificat en UTF-8.

    Returns:
        Llista de noms normalitzats, en l ordre del fitxer.

    Raises:
        FileNotFoundError: Si el fitxer no existeix.
        UnicodeDecodeError: Si el fitxer no esta en UTF-8.
    """
    with open(ruta, encoding="utf-8") as f:
        return [linia.strip().lower() for linia in f if linia.strip()]

L'apartat Raises és el que més s'oblida i sovint el més útil: avisa qui crida que aquesta funció pot fallar i de què s'haurà de protegir. Com es capturen aquestes excepcions és justament el tema de la lliçó següent.

Solució 3.

# Informes Alba

Genera un resum mensual de tasques per responsable a partir del `tasques.json`
que produeix TascaFacil, per a la revisio d equip del primer dilluns de cada mes.

## Requisits

- Python 3.10 o superior i un `tasques.json` de TascaFacil 0.18 o posterior.

La primera frase és la més important de tot el fitxer: diu què és el programa i per a qui, i hi ha lectors que no llegiran res més. Quant a les versions: (a) és un pedaç (0.18 → 0.18.1), perquè corregeix un error sense canviar la manera de fer servir el programa; (b) és una versió menor (0.18 → 0.19), funcionalitat nova que no trenca res de l'anterior; i (c) és un canvi major, perquè tot el codi que creava tasques amb dies deixa de funcionar: si el projecte ja estigués a la 1.0, passaria a la 2.0.

Conclusió

Documentar és escriure allò que el codi no pot dir per si sol, i té tres eines amb tres destinataris diferents. Els comentaris (#) expliquen el perquè i no el què: regles de negoci, decisions descartades, advertiments i paranys trobats a base d'hores; tot el que repeteixi la línia del costat sobra, i tot comentari que no s'actualitza acaba mentint, cosa que és pitjor que faltar. Els marcadors TODO, FIXME, HACK i NOTE deixen constància del que està pendent al punt exacte on és. Les docstrings, amb cometes triples i primera línia imperativa segons la PEP 257, viuen en mòduls, paquets, classes i funcions, es consulten amb help() i __doc__, i s'escriuen en un dels tres estils habituals —Google, NumPy o reStructuredText—; aquí triem Google, i el decisiu és no barrejar-los. Les anotacions de tipus (str, list[str], dict[str, int], Tasca | None, -> None) són documentació que a més entén l'editor, amb l'advertiment clar que Python no les comprova en execució: per a això hi ha mypy. El README.md és la porta d'entrada del projecte i respon en ordre a què és, què necessita, com s'instal·la, com es fa servir, com està organitzat i sota quina llicència; el CHANGELOG.md explica què va canviar a cada versió, i el versionatge semàntic MAJOR.MENOR.PEDAÇ explica d'on surten els números que aquest curs fa servir des del principi. Amb python -m pydoc -b tot això es converteix en documentació navegable sense instal·lar res, i Sphinx o MkDocs farien el mateix a gran escala.

TascaFàcil és ara la v0.18: mateix comportament, però amb docstring de mòdul a cada fitxer, Tasca i Agenda completament documentades, anotacions de tipus a les funcions públiques i un README.md que permet a qualsevol engegar el programa en cinc minuts. El projecte s'entén. El que encara no fa és aguantar: si el tasques.json està corrupte o algú escriu «tres» on el programa espera un número de dies, el resultat continua sent un traceback a la cara de l'usuari i la sessió perduda. És la promesa que el curs arrossega des de 02-04 i des de 05-05, i li toca el torn a Depuració i gestió d'errors: llegir un traceback sense por, capturar amb try/except només el que s'ha de capturar, llançar excepcions pròpies com TascaInvalida, registrar el que passa amb logging en lloc de fer-ho amb print i depurar amb punts d'interrupció en comptes d'endevinar.

Documentació i Comentaris

Contingut

Per a qui es documenta

Comentaris: la regla d'or

Comentaris que menteixen i marcadors `TODO`/`FIXME`

Docstrings: la convenció PEP 257

Els tres estils: Google, NumPy i reStructuredText

Anotacions de tipus: documentació executable

El `README.md` del projecte

`CHANGELOG.md`, versionatge semàntic i eines

TascaFàcil v0.18: el paquet documentat

Errors Habituals i Consells

Exercicis

Exercici 1: Comentaris que aporten

Exercici 2: Docstring i anotacions

Exercici 3: Versionatge i CHANGELOG

Solucions

Conclusió

Fonaments de la Programació

Mòdul 1: Introducció a la Programació

Mòdul 2: Conceptes Bàsics

Mòdul 3: Estructures de Control

Mòdul 4: Funcions i Procediments

Mòdul 5: Estructures de Dades

Mòdul 6: Algorismes Bàsics

Mòdul 7: Objectes i Organització del Codi

Mòdul 8: Bones Pràctiques i Eines

Mòdul 9: Projecte Final i Tancament del Curs

Documentació i Comentaris

Contingut

Per a qui es documenta

Comentaris: la regla d'or

Comentaris que menteixen i marcadors TODO/FIXME

Docstrings: la convenció PEP 257

Els tres estils: Google, NumPy i reStructuredText

Anotacions de tipus: documentació executable

El README.md del projecte

CHANGELOG.md, versionatge semàntic i eines

TascaFàcil v0.18: el paquet documentat

Errors Habituals i Consells

Exercicis

Exercici 1: Comentaris que aporten

Exercici 2: Docstring i anotacions

Exercici 3: Versionatge i CHANGELOG

Solucions

Conclusió

Fonaments de la Programació

Mòdul 1: Introducció a la Programació

Mòdul 2: Conceptes Bàsics

Mòdul 3: Estructures de Control

Mòdul 4: Funcions i Procediments

Mòdul 5: Estructures de Dades

Mòdul 6: Algorismes Bàsics

Mòdul 7: Objectes i Organització del Codi

Mòdul 8: Bones Pràctiques i Eines

Mòdul 9: Projecte Final i Tancament del Curs

Comentaris que menteixen i marcadors `TODO`/`FIXME`

El `README.md` del projecte

`CHANGELOG.md`, versionatge semàntic i eines