agentic-studio/network-poc/tests/golden-examples/DOCUMENTATION.md

Dokumentointiohjeet — Zensical

Hyvä dokumentointi kertoo mitä asia ON, ei mitä se tekee. Se on kuin zen-koan: lyhyt, tarkka, riittävä.

Periaatteet

1. Yksi rivi riittää. Jos tarvitset kappaleen, koodi on liian monimutkainen.
2. Kerro mitä, älä miten. """Tietokantamallit — SQLAlchemy 2.0, SQLite.""" ei """This module creates database models using SQLAlchemy..."""
3. Älä toista koodia. Jos funktio on create_todo, docstring ei ole "Creates a todo".
4. Suomi tai englanti, ei molempia. Valitse yksi kieli per projekti.
5. Ei täytesanoja. "This module provides functionality for" → poista.

Mitä dokumentoidaan

Kohde	Dokumentointi	Esimerkki
Moduuli (.py)	Aina. Yksi rivi: mitä tiedosto sisältää.	"""Pydantic v2 -skeemat — Create ja Response."""
Luokka	Aina. Mitä entiteetti edustaa.	"""Tehtävä — otsikko, deadline, prioriteetti."""
Funktio	Vain jos nimi ei kerro kaikkea.	get_db → """Tietokantasessio per pyyntö."""
CRUD-endpoint	Ei. Nimi + HTTP-metodi riittää.	create_todo, list_todos — itsedokumentoivia
Testi	Ei. Testin nimi on dokumentaatio.	test_get_todo_not_found — selvä
Konfiguraatio	Kommentti vain jos arvo yllättää.	check_same_thread: False # SQLite + FastAPI

Mitä EI dokumentoida

• Importteja
• Ilmeisiä parametreja (item_id: int)
• Tyyppivihjeitä jotka kertovat saman asian
• Geneerisiä "boilerplate"-docstringejä

Esimerkkejä

Hyvä (zensical)

"""Tietokantamallit — SQLAlchemy 2.0, Mapped-tyypitys, SQLite."""

class Todo(Base):
    """Tehtävä — otsikko, kuvaus, deadline, prioriteetti ja status."""
    ...

def get_db():
    """Tietokantasessio per pyyntö."""
    ...

Huono (verbose)

"""
This module defines the database models for the Todo application.
It uses SQLAlchemy ORM to create the database tables and provides
the session factory for database connections.
"""

class Todo(Base):
    """
    Represents a todo item in the database.

    Attributes:
        id: The unique identifier for the todo item.
        title: The title of the todo item.
        ...
    """
    ...

Huono (tyhjä)

# Ei docstringejä ollenkaan — lukija ei tiedä mikä tiedoston rooli on
class Todo(Base):
    __tablename__ = "todos"
    ...

Tarkistuslista

Generoitu koodi on hyvin dokumentoitu kun:

• Jokainen .py-tiedosto alkaa yksirivisellä docstringillä
• Jokainen luokka kertoo mitä entiteetti edustaa
• Docstringit ovat saman kielen kuin muu koodi
• CRUD-endpointeilla ei ole turhia docstringejä
• Kommentteja on vain siellä missä koodi yllättää