Siirrä kipina-codebench projektin päätasolle

kipina-codebench/golden-examples/DOCUMENTATION.md

@@ -0,0 +1,84 @@
+# 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)
+
+```python
+"""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)
+
+```python
+"""
+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ä)
+
+```python
+# 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ää