Kommentit
- Määritä kieli, jonka haluat dokumentoida, standardit ja työkalut vaihtelevat kielittäin .
- Aloita tällä: Mitä ohjelmistosi piti ratkaista / tehdä? Dokumentoi vaiheet siitä, miten se ensisijaisesti tekee.
- Löydä olemassa oleva koodi olemassa olevista avoimen lähdekoodin projekteista. Lue olemassa oleva koodi. Sitten vertaa sitä omasi. Lopuksi, kun olet tehnyt tämän, kysy tiettyjä kysymyksiä löytämäsi koodin perusteella.
Vastaa
Sinun tulee dokumentoida:
- tarkoitus, miksi;
ja
- mikä ei välttämättä ole selvää, miten.
Miksi optimoit tämän bitin, mihin oikeastaan kyseinen pikakuvake on, mitä odotat tuloksen, mikä on vaatimus, miksi syy siihen on Ensinnäkin, mihin nämä tiedot lähetetään, mistä saat syötteen, jos tämä on monisäikeinen, selitä malli, jos tietokantaa on, selitä kaavio, linkit, miksi …
Älä dokumentoi ilmeistä. Esitykseen on monia tapoja tehdä se. Pidän henkilökohtaisesti sisäisistä kommenteista (olen vanhempi ohjelmoija, eikä meillä ollut tuolloin hienoja työkaluja – plus minä vain yksinkertainen ja suoraviivainen). Jos haluat jotain hienoa, varmista, että se ei kuluta liikaa aikaa tai muuten todennäköisesti hylkäät sen.
Kommentit
- Tarkoitus on usein hyödyllisin asia, voin tarkastella koodia ja ymmärtää, mitä se tekee, mutta ymmärtää, miksi kehittäjä teki sen tällä tavalla, voi olla erittäin hyödyllistä.
Vastaa
Lue oma koodi, jonka kirjoitit vähintään 2 vuotta sitten.
Kysy itseltäsi, minkä tyyppiset asiat ovat epäselviä, ja jätä sinut raapimaan päätäsi Tämän tyyppiset asiat (mitä ne ovatkin, ne ovat erilaisia eri ohjelmoijille) ovat niitä, jotka haluat aloittaa dokumentoimalla ensin jokaisen kehittämäsi koodin tai vanhan koodin, jonka kirjoitat uudelleen / uudelleen. Kaikki muotoilut, jotka hidastavat ymmärrystäsi , muutos.
Tai muuten, 2 vuoden kuluttua …
Vastaa
Yksi asia, jonka sinun pitäisi include on riippuvuudet. Jos funktio perustuu johonkin tuolta , sitten doc muistuttaa mitä se on, missä siellä on ja miksi.
Vastaa
Koska käytät PHP: tä, PHPDoc olisi hyvä paikka aloittaa. Voit rakentaa API-dokumentaation lähdekoodiin ja käyttää sitten samaa muotoa opetusohjelmien ja käyttäjädokumentaation kirjoittamiseen. Saat myös joustavuutta ulostulomuodossa.
Vastaa
Aloitan koodin kirjoittamisen kirjoittamalla ensin kommenttini. Kuvaile ohjelman kulkua ja alat ymmärtää, mitä on kommentoitava ja mitä ei. Kun olet aloittanut koodin kirjoittamisen, koristele ne osat, jotka tarvitsevat lisäselvityksiä, ja tarkennat itse dokumentoivat osat.
Kun jokainen luokka, toiminto tai menetelmä on valmis, palaan takaisin ja lisätään kommentteja asiakirjageneraattorille, kuten doxygen tai PHPDoc. Tämä antaa sinulle todelliset API-ohjeet.
Riippuen siitä, kuka kuluttaa koodia, kirjoitan virallisen kuvauksen toimintadokumentista joko LaTeX: ssä tai Wordissa.
Vastaus
Doxygen kattaa useimmat kielet. Sinun on käytettävä jonkin aikaa syntaksin ymmärtämiseen, mutta iso asia on, mitä dokumentoidaan. Käsittele kutakin toimintoa mustana laatikkona. Dokumentoi, mikä menee sisään ja mikä menee ulos. Dokumentoi, mitä virheitä se loukkaa, voivatko argit olla nollaa, voiko se palauttaa nollan.
Muista, että muutamassa kuukaudessa et pysty selvittämään, mitä helvettiä funktio tekee. Säästät vain itsellesi aikaa.