Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Automaattinen dokumentaatio

Oppitunti 8 / 20 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Dokumentointi keskeyttämättä kehitystä
  2. Sisäinen dokumentaatio: JSDoc ja kommentit
  3. README-tiedoston generointi
  4. API-dokumentaatio
  5. Arkkitehtuuridokumentaatio
  6. Olemassa olevan dokumentaation päivittäminen
  7. Automatisointi AGENTS.md-tiedoston avulla
  8. Keskeiset asiat

Dokumentointi keskeyttämättä kehitystä

Kaikki ovat samaa mieltä siitä, että dokumentaatio on välttämätöntä, mutta lähes kukaan ei kirjoita sitä. Miksi? Koska kirjoittaminen tapahtuu väärään aikaan: ominaisuus on valmis, ja huomio on jo siirtynyt eteenpäin. Codex siirtää tämän kustannuksen. Se analysoi koodin sellaisena kuin se on ja tuottaa täydellisen, ajantasaisen dokumentaation, joka vastaa todellista toteutusta. Tämä uskollisuus on ratkaiseva tekijä: keksitty dokumentaatio aiheuttaa enemmän haittaa kuin tyhjä sivu, koska se luo väärää luottamusta.

Sisäinen dokumentaatio: JSDoc ja kommentit

Käytetyin dokumentaatio näkyy suoraan editorin työkaluvihjeessä, juuri siellä missä kysymys herää.

"Add JSDoc documentation to all exported functions 
and types in src/lib/. Include a description, 
parameters, return type, and a usage example 
for each function."

Tässä on esimerkki siitä, mitä Codex tuottaa hintalaskentafunktiolle:

/**
 * Calculates the total price after applying the discount.
 * 
 * @param basePrice - Unit price in cents
 * @param quantity - Number of units (minimum 1)
 * @param discountPercent - Discount percentage (0-100)
 * @returns The total price in cents, rounded to an integer
 * 
 * @example
 * calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
 * 
 * @throws {ValidationError} If price or quantity is negative
 */
export function calculateTotal(
  basePrice: number,
  quantity: number,
  discountPercent: number = 0
): number {
  // ...
}

Kaksi tietoa tässä ovat kaiken arvoisia: yksikkö (sentit, ei eurot) ja negatiivisista arvoista heitettävä poikkeus. Nämä ovat juuri niitä kahta asiaa, jotka kehittäjä yleensä huomaa tuotannossa, sen jälkeen kun asiakkailta on laskutettu kymmenen kertaa vähemmän kuin oli tarkoitus. Codex poimi nämä tiedot toteutuksesta, ei yleisestä kommenttipohjasta.

README-tiedoston generointi

Uutta projektia varten tai kun README on muuttunut fiktioksi koodin ajautumisen vuoksi, listaa asiat, jotka lukijan on pystyttävä tekemään luettuaan tiedoston.

"Generate a comprehensive README.md for this project. Include:
- Project description and purpose
- Prerequisites (Node.js, PostgreSQL, etc.)
- Step-by-step installation instructions
- Required environment variables (without values)
- Available commands (dev, test, build, lint)
- Project structure
- How to contribute"

Codex hyödyntää package.json-tiedostoa, konfiguraatiotiedostoja ja todellista hakemistorakennetta tuottaakseen dokumentin, joka heijastaa projektin nykytilaa. Ohje “ilman arvoja” ei ole oikku: ilman sitä agentti, joka on juuri lukenut hyvin täytetyn .env.example-tiedoston, saattaisi mielellään kopioida arvot, joita et halua versionhallinnassa olevaan tiedostoon.

API-dokumentaatio

REST-rajapinnalle kustannustehokkain dokumentaatio on sellainen, jota muut työkalut voivat kuluttaa ilman ihmisen väliintuloa.

"Analyze all routes in src/api/routes/ and generate 
an openapi.yaml file. Include request and response 
schemas based on existing TypeScript types and 
Zod validations."

Kaikki poimitaan koodista: reittipolut, HTTP-metodit, validointiskaemat ja vastauksen tyypit. Tuloksena oleva spesifikaatio on siten uskollinen toteutukselle, mikä mahdollistaa sen, että kuluttajasi voivat johtaa siitä tyypitetyn asiakaskirjaston tai testikokoelman kysymättä sinulta mitään.

Arkkitehtuuridokumentaatio

Arkkitehtuuripäätöksiä harvoin kirjataan ylös. Kun niitä kirjataan, ne kuvaavat alkuperäistä aikomusta eivätkä todellisuutta kolme vuotta myöhemmin. Pyydä Codexia formalisoimaan se, mitä koodissa todella on.

"Analyze the project architecture and create a 
docs/architecture.md file documenting:
- Layers (API, services, repositories, models)
- Data flow for a typical request
- Patterns used (repository pattern, dependency injection)
- Dependencies between modules"

Tällä dokumentilla on odottamaton sivuhyöty: kuvaamalla moduuliriippuvuudet sellaisina kuin ne todella ovat, se paljastaa kytköksiä, joita kukaan ei ole tunnustanut – kuten laskutuspalvelun tuovan utiliteetin todennusmoduulista.

Olemassa olevan dokumentaation päivittäminen

Vanhentunut dokumentaatio on pahempaa kuin ei dokumentaatiota lainkaan, koska se tuhlaa aikaa auktoriteetilla varustettuna.

"Compare README.md with the current state of the project. 
Identify outdated sections (commands that no longer exist, 
removed dependencies, incorrect instructions). 
Update the README accordingly."

Codex asettaa jokaisen README-väittämän vastakkain todellisen koodin kanssa ja korjaa ristiriidat. Ajoita tämä tehtävä säännöllisesti, esimerkiksi ennen jokaista julkaisua, äläkä odota siihen päivään, jolloin uusi työntekijä huomaa, ettei yksikään asennuskomento toimi.

Automatisointi AGENTS.md-tiedoston avulla

Lopeta dokumentaation kohteleminen erillisenä rutiinina ja tee siitä projektin pysyvä rajoite.

## Documentation
- Every new exported function MUST have complete JSDoc
- API changes MUST update openapi.yaml
- Comment format: French for business logic, English for technical details

Näillä kolmella säännöllä jokainen kehitystehtävä sisältää oman dokumentaatiopäivityksensä. Kuilu koodin ja kuvauksen välillä lakkaa kasvamasta hiljaa, mikä on ainoa kestävä tapa voittaa tämä taistelu.

Keskeiset asiat

  • Codex generoi dokumentaation, joka on uskollinen todelliselle koodille, ei keksittyä
  • Sisäinen dokumentaatio (JSDoc) on hyödyllisin päivittäisessä työssä
  • Codex voi tuottaa README-tiedostoja, OpenAPI-spesifikaatioita ja arkkitehtuuridokumentaatiota
  • Käytä Codexia tunnistamaan ja korjaamaan vanhentunutta dokumentaatiota
  • Lisää dokumentaatiosäännöt tiedostoon AGENTS.md prosessin automatisoimiseksi