jaakko
d6a544909c
- golden-examples/todo/: 6/6 PASS referenssitoteutus - SQLAlchemy 2.0 (DeclarativeBase, Mapped, mapped_column) - Pydantic v2 (ConfigDict) - PEP 621 pyproject.toml, Python >=3.14 - Uniikki testidata per testi - CODE_SYSTEM päivitetty: few-shot kultaisesta esimerkistä - DOCUMENTATION.md: zensical-dokumentointiohjeet
2.7 KiB
2.7 KiB
Dokumentointiohjeet — Zensical
Hyvä dokumentointi kertoo mitä asia ON, ei mitä se tekee. Se on kuin zen-koan: lyhyt, tarkka, riittävä.
Periaatteet
- Yksi rivi riittää. Jos tarvitset kappaleen, koodi on liian monimutkainen.
- Kerro mitä, älä miten.
"""Tietokantamallit — SQLAlchemy 2.0, SQLite."""ei"""This module creates database models using SQLAlchemy...""" - Älä toista koodia. Jos funktio on
create_todo, docstring ei ole "Creates a todo". - Suomi tai englanti, ei molempia. Valitse yksi kieli per projekti.
- 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ää