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
85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
# 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ää
|