Voitot:
- Kyky tuottaa README-, docstring- ja muutoslokiluonnoksia kohdeyleisön ja lähteen perusteella tekoälyllä
- Kyky erottaa "mitä/miten"- ja "miksi"-kerrokset dokumentaatiossa ja lisätä "miksi" ihmisenä
- Asennusvaiheiden tarkistaminen suorittamalla ne henkilökohtaisesti ja tekemällä asiakirjasta osa koodin muutosta
Ohjelmiston yleisimmin laiminlyöty, mutta pisimpään kestävä osa on dokumentointi. Koodi on luettavissa jopa kuukausien jälkeen; Sen kirjoittaja on poissa, konteksti unohdetaan ja vain se, mikä kirjoitettiin, on jäljellä. Hyvä README (johdantodokumentti, joka selittää, mikä projekti on ja kuinka se asennetaan ja suoritetaan), selittävät koodikommentit ja ajan tasalla oleva API-dokumentaatio (viite, joka selittää käyttöliittymän käytön) määräävät suoraan tiimin nopeuden. Tekoäly poistaa suuren osan "kirjoitusväsymyksestä" dokumentaatiosta – mutta sen mukana tulee ansa: tekoäly voi päätellä koodista, mitä se tekee, mutta ei useinkaan tiedä, miksi se tehdään niin.
Tässä osiossa opit tuottamaan README:n, koodikommentin, docstringin (toiminto/luokkakohtainen kommenttilohko), API-asiakirjan ja muutoslokin tekoälyllä; ja kuinka säilyttää inhimillisesti dokumentaation arvokkain osa: "miksi".
Ero "mitä" ja "miksi" välillä
Dokumentaatiossa on kaksi tasoa. Ensimmäinen on mitä/miten: "tämä funktio lajittelee luettelon", "asenna suorittamalla tämä komento". Nämä voidaan poimia koodista ja rakenteesta; AI loistaa tässä. Toiseksi miksi: "miksi teimme tästä palvelusta asynkronisen synkronisen sijaan", "miksi tämä raja-arvo on 30 sekuntia", "miksi valitsimme tämän kirjaston toisen sijaan". Näitä ei ole kirjoitettu koodiin; Se on suunnittelupäätösten, rajoitusten ja menneen tuskan tuote.
AI ei tiedä "miksi"; Parhaimmillaan se muodostaa järkevän arvauksen – mikä on vaarallista, koska väärä syy on pahempi kuin ei syytä ollenkaan. Joten työnjako on selvä: tekoäly luonnostelee "mitä/miten", lisäät "miksi". Arvokkain kommentti on se, joka kertoo sen, mitä koodi ei voi sanoa.
Vinkki: Älä toista kommentilla sitä, mitä itse koodi selvästi sanoo (kuten i = i + 1 // lisää i:tä yhdellä). Tekoäly tuottaa joskus tällaisia tarpeettomia kommentteja; Poista ne ja keskitä energiasi "miksi"-kommentteihin.
Askel askeleelta: Dokumentaation luominen tekoälyllä
- Määritä kohdeyleisö. "Juuri aloittava kehittäjä", "ulkoinen tiimi, joka käyttää tätä APIa", "tulevaisuus minä" - yleisö määrittää kielen ja syvyyden sävyn.
- Anna lähde. Lisää kehotteeseen asiaankuuluva koodi, olemassa oleva README, käyttöesimerkki. Lähteetön asiakirja on kutsu valmistukseen.
- Asetusrakenne. Standardiosat README:lle (Tarkoitus, Asennus, Käyttö, Kokoonpano, Osallistuminen), dokumenttijonon projektimuoto.
- Merkitse "miksi"-välit. Pyydä tekoälyä merkitsemään päätökset, joille se ei tiedä perusteluja, "miksi-huomautus vaaditaan tässä"; Sitten täytät nämä kohdat.
- Vahvista. Suorita itse asiassa asennusvaiheet; kokeile mallikoodia. README, joka ei toimi, on huonompi kuin ei README ollenkaan.
Kolme minikoteloa
Tapaus 1 – README nopeutettu käyttöönotto. Avoimen lähdekoodin työkalun README puuttui; Uudet kirjoittajat kamppailivat asennuksen kanssa keskimäärin 2 tuntia. Tiimi antoi asennusskriptit ja package.jsonin tekoälylle ja laati jäsennellyn README:n, suoritti sitten vaiheet itse puhtaalla koneella ja lisäsi kaksi puuttuvaa riippuvuutta. Seuraavien tekijöiden asennusaika lyheni keskimäärin 25 minuuttiin.
Tapaus 2 – keksitty "miksi"-ansa. Kehittäjä pyysi tekoälyltä kommenttia aikakatkaisuarvon viereen (timeout = 30). Tekoäly kirjoitti kohtuullisen mutta virheellisen perustelun "siedetä korkean verkon latenssin"; todellinen syy oli loppupään palvelun sopimusperusteinen 30 sekunnin raja. Väärintulkinta sai seuraavan kehittäjän tarpeettomasti lisäämään arvoa, mikä johti tapaukseen. Oppitunti: koodin omistajan on tarkistettava perustelu.
Tapaus 3 – Docstring-standardi on automatisoitu. Apumoduulissa, jossa oli 40 toimintoa, ei ollut dokumenttijonoja. Tekoälylle annettiin projektimuoto (Google-tyyli) ja se tuotti parametrien, palautusten ja poikkeusten kuvaukset kullekin toiminnolle; Kehittäjä tarkisti nämä ja korjasi muutaman virheellisen tyyppiilmoituksen. 40 toiminnon dokumentointi väheni noin puolesta päivästä tuntiin.
Neljä kopioitavaa mallia
Strukturoitu README-luonnos:
Kohdeyleisö: {{esim. uusi avustaja}}. Kirjoita README-luonnos alla olevien tiedostojen perusteella. Osiot: Tarkoitus, Ominaisuudet, Vaatimukset, Asennus, Käyttö, Kokoonpano, Testaus, Osallistuminen. Pura asennus-/ajokomennot todellisista tiedostoista; ASENNUS. Merkitse paikat, joista et ole varma "[VAHVISTA]". Lähde: {{package.json / scripts / esimerkkikoodi}}
Docstring/API-viite:
Kirjoita dokumenttimerkkijono näihin funktioihin muodossa {{projektin tyyli: Google/NumPy/JSDoc}}: lyhyt yhteenveto, parametrit (tyyppi + merkitys), paluu, poikkeukset, 1 lyhyt esimerkki. Älä toista sitä, mitä koodi selkeästi sanoo. Merkitse "miksi" vaativat suunnittelupäätökset "[MIKSI TARPEEN]", älä kirjoita tekosyitä perusteluja.{{code}}
Poista välilyönnit "miksi"-kommentista:
Tässä koodissa seuraava kehittäjä saattaa kysyä "miksi näin?" (maagiset numerot, epätavalliset päätökset, kiertotavat). Kommentoi jokaiselle LUUNTO, mutta jätä perustelut TYHJÄ; Täytän perustelut.{{code}}
Muutosloki/PR lausunto:
Kirjoita {{muutoslokimerkintä / PR-kuvaus}} alla olevasta erotuksesta. Muoto: Mikä muuttui (käyttäjäkielellä), miksi (ongelma: {{...}}), rikkova muutos (jos sellainen on), Onko se testattu. Muokkaa teknistä ammattislangia kohdeyleisön mukaan.{{diff}}
Heikko kehote / Vahva kehote
Heikko: "Kirjoita README tälle projektille."
Vahva: "Kohdeyleisö: kehittäjä, joka kloonaa tämän repon ensimmäistä kertaa. Kirjoita liitteenä olevan package.jsonin, docker-compose.yml:n ja scripts/-kansion perusteella README-luonnos, jossa on Tarkoitus, Vaatimukset, Asennus, Käyttö, Testaus, Osallistuminen. Pura komennot näistä tiedostoista, älä keksi niitä; merkitse [VERIFY]."
Vahva versio antaa yleisölle, lähteelle, rakenteen ja "tee, merkitse" -säännön; niin, että asiakirja perustuu oikeisiin tiedostoihin ja tarkistettavat paikat ovat selvästi näkyvissä.
Asiakirjan tyyppi
AI pärjää hyvin
Ihminen lisää/tarkistaa
README asennus
askel ääriviivat
Suorita vaiheet ja vahvista
Docstring/API
Rakenne, parametri, tyyppi
Oikea tyyppi ja "miksi"
Koodikommentti
"Mitä hän tekee" yhteenveto
"Miksi tämä on" perustelu
Muutosloki/PR
ensimmäinen luonnos
Vaikutus ja tarkkuus
Arkkitehtoninen päätös (ADR)
luuranko
Todellisia päätöksiä ja kompromisseja
Dokumentaatio vaatii huoltoa
Asiakirjan vaarallisin puoli on, kun se näyttää todelta, vaikka se on väärä. Kun koodi muuttuu ja dokumenttia ei päivitetä, se johtaa aktiivisesti lukijaa harhaan. AI tekee päivittämisestä helppoa: anna ero ja kysy "mihin asiakirjan osiin tämä muutos vaikuttaa?" voit kysyä. Mutta se on prosessi, joka varmistaa ajantasaisuuden – tee dokumentaation päivityksestä osa koodin muutosta (PR:n hyväksymiskriteeri). AI kiihtyy; Joukkue rakentaa kurinalaisuutta.
Varoitus: Älä julkaise tarkistamatta asennuksen vaiheita README:ssä. "Todennäköisesti toimiva" asiakirja voi pilata uuden kehittäjän ensimmäisen päivän ja heikentää luottamusta. Suorita vaiheet itse puhtaassa ympäristössä.
Yleisiä virheitä
- AI:n "miksi" sopiminen. Väärä perustelu on pahempaa kuin ei perusteluja; Koodin omistajan tulee kirjoittaa suunnittelun syy.
- Asennusvaiheita ei tarkisteta. README, joka ei toimi, tuhoaa luottamuksen.
- Tarpeeton kommentti, joka toistaa koodia. Se tuottaa kohinaa, hämärtäen todellisia "miksi"-tulkintoja.
- Kohdeyleisöä ei määritellä. Asiakirjasta, joka on epäselvä, kenelle se on kirjoitettu, ei ole hyötyä aloittelijalle eikä asiantuntijalle.
- Päivityksen erottaminen prosessista. Jos asiakirjaa ei päivitetä koodilla, siitä tulee nopeasti harhaanjohtava.
Yhteenvetona
AI poistaa suuren osan mekaanisesta taakasta dokumentaatiosta: nopeat luonnokset README, docstring, API-viittaus, muutosloki ja PR-kuvaukset. Mutta se ei voi tietää "miksiä", joka on arvokkain kerros, ja sen keksiminen on vaarallista. Työnjako on selvä: tekoäly tuottaa "mitä/miten", lisäät "miksi". Määritä yleisö, tarjoa resursseja, määritä rakenne, merkitse sopivat paikat ja tarkista jokainen asennusvaihe suorittamalla se itse. Tee dokumentaatiosta olennainen osa koodin muutosta.
Sovellustehtävä
Valitse moduuli tai pieni projekti, jonka dokumentaatio puuttuu tai on vanhentunut. Luo ensin ääriviivat tekoälystä "strukturoidun README-luonnoksen" (tai asiakirjamerkkijonon) mallin avulla; Muista ilmoittaa lähde ja kohdeyleisö. Käy sitten läpi jokainen piste, jossa tekoäly on merkinnyt [VERIFY] tai [MIKSI TARVITSE]: suorita asennusvaiheet ja täytä "miksi" omilla tiedoillasi. Huomaa, kuinka monta vaihetta on korjattava ja kuinka monta "miksi" lisäsit.
tarkistuslista
- [ ] Erotan dokumentaatiossa "mitä/miten"- ja "miksi"-tasot.
- [ ] En tee tekoälystä "miksi", lisään sen itse.
- [ ] Annan kehotteeseen kohdeyleisön ja varsinaiset lähdetiedostot.
- [ ] Vahvistan tekoälyn merkitsemät [VERIFY]-pisteet suorittamalla ne henkilökohtaisesti.
- [ ] Poistan tarpeettomat kommentit, jotka toistavat koodia.
- [ ] Teen dokumentaation päivityksen osaksi koodin muutosta.