Siellä on joitain hyviä esimerkkejä hyvin dokumentoidusta koodista, kuten java api. Mutta monet julkisten hankkeiden koodit, kuten git ja yritysten sisäiset projektit, on huonosti dokumentoitu eikä kovin tulokasystävällinen.

Kaikissa ohjelmistokehityksessäni olen joutunut käsittelemään huonosti dokumentoitua koodia. Huomasin seuraavat asiat –

  1. vähän tai ei lainkaan kommentteja koodissa.
  2. Menetelmän ja muuttujien nimet eivät kuvaa itseään.
  3. On vähän tai ei lainkaan dokumentaatiota siitä, kuinka koodi sopii järjestelmään tai liiketoimintaprosesseihin.
  4. Huonojen kehittäjien palkkaaminen tai hyvien mentorointi. He eivät voi kirjoittaa yksinkertaista ja puhdasta koodia. Siksi on vaikea tai mahdotonta kenenkään, myös kehittäjän, dokumentoida koodia.

Tämän seurauksena olen joutunut käymään läpi paljon koodaa ja puhu monien ihmisten kanssa oppiaksesi asioita. Minusta tämä tuhlaa kaikkien aikaa. Se myös luo tarpeen projektin uusille tulijoille KT / tiedonsiirtoistuntoja.

Olen oppinut, että asiakirjoihin ei kiinnitetä ansaitsemansa huomiota seuraavista syistä:

  1. Laisku.
  2. Kehittäjät eivät halua tehdä muuta kuin koodata.
  3. Työturvallisuus. (Jos kukaan ei ymmärrä koodiasi helposti, et ehkä ole helposti vaihdettavissa.)
  4. Vaikeat määräajat jättävät vähän aikaa dokumentointiin.

Joten mietin, onko olemassa keino rohkaista ja valvoa hyviä dokumentointikäytäntöjä yrityksessä tai projektissa. käytetään luomaan kunnollista dokumentaatiota minkä tahansa projektin järjestelmille ja koodille sen monimutkaisuudesta riippumatta? Onko olemassa hyviä esimerkkejä siitä, milloin dokumentaatiota tarvitaan vähän tai ei ollenkaan?

IMHO, mielestäni meidän olisi pitänyt dokumentaation tarkistus projektin toimittamisen jälkeen. Jos se ei ole yksinkertainen, tiivis, havainnollistava ja käyttäjäystävällinen, kehittäjä tai teknisen dokumentoinnin insinööri omistaa vastuun siitä ja joutuu korjaamaan sen. En myöskään odota ihmisten tekevän dokumentaatioita uudelleen, ei toivoa, että se on käyttäjäystävällinen kuin pääkirjat, mutta odotan sen poistavan tarpeen tuntia analyysiä ja tuhlaavia KT-istuntoja.

Onko keino lopettaa tai lievittää tätä hulluutta? ”Asiakirjapohjainen kehitys” ehkä?

Kommentit

  • On myös toinen syy, miksi oikeaa dokumentaatiota ei usein ole: On erittäin vaikea kirjoittaa hyvää dokumentaatiota, joka ei ’ t vain muotoilee koodin englanniksi, mutta kuvaa miksi koodi suunnitellaan / kirjoitetaan tällä tavalla. Näiden tietojen tarve käy ilmeiseksi vasta kuukausia sen jälkeen, kun ne olisi pitänyt kirjoittaa.
  • Toinen vakava syy: monilla kehittäjillä on englanti toisena kielenä ja / tai he kirjoittavat huonosti englantia . Saatat vain pakottaa heidät kirjoittamaan yhden linjan menetelmää varten, mutta jos haluat hyvää dokumentaatiota, sinun on parempi valmistautua maksamaan siitä ja palkata asiantuntijoita tekemään niin.

Vastaa

Kuinka dokumentoida koodi?

Sinulla on jo vihje: katso kuinka Java-sovellusliittymä dokumentoidaan.

Yleisesti ottaen ei ole olemassa ainutlaatuista sääntöjoukkoa, joka soveltuu kaikkiin projekteihin. Kun työskentelen yrityskriittisten suurten projektien parissa, dokumentaatiolla ei ole mitään tekemistä sen kanssa, jonka kirjoitan pieneen avoimen lähdekoodin kirjastoon, jolla puolestaan ei ole mitään tekemistä keskisuuren henkilökohtaisen projektini dokumentaation kanssa. .

Miksi monia avoimen lähdekoodin projekteja ei ole dokumentoitu hyvin?

Koska useimmat avoimen lähdekoodin projektit ovat ihmisiä, jotka osallistuvat kyseisiin projekteihin, koska se on hauskaa. Useimmat ohjelmoijat ja kehittäjät katsovat että dokumentaation kirjoittaminen ei ole tarpeeksi hauskaa tehdä ilmaiseksi.

Miksi monet suljetun lähdekoodin projektit ei ole dokumentoitu hyvin?

Koska (1) hyvien asiakirjojen kirjoittaminen ja (2) ylläpito maksaa valtavasti rahaa.

  1. Välitön kustannukset (dokumentaation kirjoittamisen kustannukset) ovat selkeästi sidosryhmien nähtävissä: jos tiimisi pyytää viettämään seuraavat kaksi kuukautta projektin dokumentoinnissa, se maksaa kaksi ylimääräistä kuukausipalkkaa.

  2. Lo Lyhytaikaiset kustannukset (dokumentaation ylläpitokustannukset) tulevat havaittaviksi melko helposti myös johtajille, ja ne ovat usein ensimmäinen kohde, kun heidän on alennettava kustannuksia tai lyhennettävä viivästyksiä. Tämä aiheuttaa ylimääräisen ongelman vanhentuneesta dokumentaatiosta, josta tulee nopeasti hyödytöntä ja jonka päivittäminen on erittäin kallista.

  3. Pitkän aikavälin säästöt (säästöt, jos sinun ei tarvitse hukata muutama päivä tutkiaksesi vanhan koodin ymmärtämiseksi vain perusasiat, jotka olisi pitänyt dokumentoida vuosia sitten) on toisaalta vaikea mitata, mikä vahvistaa joidenkin johtajien käsityksen, että asiakirjojen kirjoittaminen ja ylläpito on ajanhukkaa.

Havaitsen usein seuraavaa:

  1. Alussa tiimi on valmis dokumentoimaan paljon.

  2. Ajan myötä määräaikojen paine ja kiinnostuksen puute vaikeuttavat dokumentaation ylläpitoa.

  3. Muutama kuukausi myöhemmin uusi henkilö, joka liittyy projektiin, ei käytännössä voi käyttää dokumentaatiota, koska se ei vastaa lainkaan varsinaista järjestelmää.

  4. Huomaa, että johto syyttää kehittäjiä dokumentaation pidättämättä jättämisestä; kehittäjät pyytävät viettämään muutaman viikon päivittämiseen.

    • Jos johto myöntää muutaman viikon siihen, sykli toistuu.

    • Jos johto kieltäytyy aiemman kokemuksen perusteella, se vain lisää huonoa kokemusta, koska tuotteelta puuttuu dokumentaatio, mutta kirjoittamiseen ja ylläpitoon käytettiin muutama kuukausi.

Dokumentaation tulisi olla jatkuva prosessi, kuten testaus. Vietä viikko vain muutaman tuhannen LOC: n koodaamisella, ja paluu testeihin ja dokumentointiin on erittäin, tuskallista. dokumentaatio?

Vastaavasti tapoja rohkaista ihmisiä kirjoittamaan puhdas koodi, tekemään säännöllisiä korjauksia, käyttämään suunnittelumalleja tai lisäämään tarpeeksi yksikkötestejä.

  • Näytä esimerkki. Jos kirjoitat hyvää dokumentaatiota, myös parisi voivat alkaa tehdä sitä.

  • Tee järjestelmällisiä koodiarvosteluja, mukaan lukien viralliset koodiarvostelut, joiden tarkoituksena on tarkastaa dokumentaatio.

  • Jos jotkut ryhmän jäsenet ovat erityisen antipatisoisia hyvään dokumentaatioon (tai dokumentaatioon lainkaan), keskustele asiasta heidän kanssaan yksityisesti ymmärtääkseen, mitkä esteet estävät heitä kirjoittamasta parempaa dokumentaatiota. Jos he syyttävät ajan puutetta, näet ongelmien syyn.

  • Tee asiakirjojen läsnäolo tai puute mitattavissa muutamaksi viikoksi tai kuukaudeksi, mutta älä Voit esimerkiksi mitata kommenttirivien määrää LOC: tä kohti, mutta älä tee siitä pysyvää mittaria, muuten kehittäjät alkavat kirjoittaa pitkiä mutta merkityksettömiä kommentteja vain päästä eroon matalista pisteistä.

  • Käytä pelaamista. Tämä tulee yhteen edellisen kohdan kanssa.

  • Käytä positiivista / negatiivista vahvistusta .

  • (Katso SJuan76: n kommentti ) Käsittele kommenttien puuttumista virheinä. Esimerkiksi Visual Studiossa voit tarkistaa vaihtoehdon XML-dokumentaation luomiseksi. Jos tarkistat myös, että kaikkia varoituksia pidetään virheinä, kommentin puuttuminen luokan tai menetelmän yläosasta pysäyttää kokoamisen.

    Mitä tulee kolmeen edelliseen kohtaan, tätä tulisi käyttää. varovaisesti. Käytin sitä jonkin aikaa erityisen kovan aloittelijoiden ohjelmoijaryhmän kanssa, ja se päätyi StyleCop-yhteensopiviin kommentteihin, kuten: 

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

jotka olivat, hm …, ei erityisen hyödyllisiä.

Muista: mikään automatisoitu ei voi auttaa sinua tunnistamaan huonoja kommentteja, kun ohjelmoijat haluavat kiertää sinua . Vain koodi arvostelut ja muut ihmisen tehtävät auttavat.

Onko olemassa hyviä esimerkkejä siitä, milloin asiakirjoja tarvitaan vähän tai ei lainkaan?

Arkkitehtuuria ja rakennetta selittävää dokumentaatiota ei tarvita:

  • Prototyypille

  • Henkilökohtainen projekti, joka on kirjoitettu muutamassa tunnissa tehtävän suorittamiseen, mutta on varma, että tätä projektia ei enää ylläpidetä,

  • Kaikille projekteille, joissa se on ilmeistä, kun otetaan huomioon pienen koon yhdistettynä erityisen puhtaaseen koodiin, vietät enemmän aikaa asiakirjojen kirjoittamiseen kuin kaikki tulevat ylläpitäjät koodin tutkimiseen.

Koodin sisäistä dokumentaatiota (koodikommentteja) ei tarvita joidenkin kehittäjien mukaan, kun koodi itse dokumentoi. Heille kommenttien läsnäolo ei, harvinaisissa tapauksissa lukuun ottamatta, ole hyvä merkki, mutta merkki siitä, että koodia ei ole kunnostettu tarpeeksi, jotta se olisi selkeä ilman kommentteja.

Minusta meidän pitäisi tarkistaa dokumentaatio projektin toimittamisen jälkeen.

Jos projektisi toimitetaan vähintään kerran viikossa, se on oikea tapa edetä. Jos projekti ei ole ketterä ja se toimitetaan kuuden kuukauden välein, tee säännöllisiä tarkistuksia.

Kommentit

  • Vastaanottajaan ’ miten kannustetaan ’, haluaisin lisätä, että monet IDE: t sallivat puuttuvien asiakirjojen ilmoittamisen varoituksina. Vaihtoehtoisesti ehkä dokumentaation staattinen analyysi voidaan tehdä OSB: llä (tietysti se ei yksin riitä).
  • @ SJuan76: Todellakin. Visual Studio voi jopa käsitellä kommenttien puuttumista käännösaikavirheeksi. Muokkasin vastaustani lisätäksesi siihen huomautuksen.
  • @ArseniMourzenko – luin, että voisimme kannustaa joitain Agile-asiakirjoja lisäämällä tarinoita dokumentaatioon. Mutta näiden ei pitäisi estää muita tarinoita, ts. Muiden tehtyjen tarinoiden määritelmä, eivät saa sisältää dokumentointikertomusten loppuun saattamista. Kuinka se kuulostaa?
  • @ArseniMourzenko – haluan lisätä vastaukseesi vielä kaksi pistettä.

(1) Lisää Jiraan jne. Tehtävä koko ajan dokumentointia varten. (2) Pyydä muita asiakirjoja tarkistamaan vielä kaksi muuta henkilöä &. Tällä tavalla ihmisiä muistutetaan asiakirjasta & vältetään huonolaatuisten asiakirjojen kirjoittaminen (tarkistuksen takia). Jos et ’ et priorisoi sitä & sitä, niin siitä tulee huono. Tiedän, että Amazon tekee paljon docs & doc-arvosteluita, ehkä vähän liikaa.

Vastaa

Mielestäni sinun on tehtävä ero kommenttien ja asiakirjojen välillä. Vaikka kommentit ovat kuvaavia, niiltä puuttuu johdonmukaisuus, ne ovat hajallaan koko koodissa. Kommenttien ei tulisi koskaan korvata koodia, joka ei ole riittävän itsekuvaava, vaan sen pitäisi vihjata muita ohjelmoijia hankalille osille.

Koodin dokumentointi riippuu projektin laajuudesta. On varmasti ihmisiä, jotka uskovat, että kaikki on dokumentoitava, ja näyttää olevan helppo perustella ajatus, koska kuka uskaltaisi vastustaa dokumentoi tietoa? Onneksi ohjelmistokehitys ei ole tiedettä, ja maailma ei romahda, jos pienen ohjelmasi yksityiskohdat hämärtyvät. Nyt kun kyseessä on ammattimainen ohjelmisto, jota monet kehittäjät voivat käyttää, kyllä sinun on dokumentoitava koodi. Mutta jos olet siinä koodata kyseisellä tasolla, tiedät sen tietysti.

tl; dr

Jos pyydät jokaisen projektin dokumentoimista hyvin, niin kysyt liikaa .

Kommentit

  • Fortunately software development is not science Kerro lisää miksi uskot tämän.
  • @Borat – Ohjelmistokehitys on tekniikan ala, mikä tarkoittaa, että se käyttää tieteen tarjoamia työkaluja.
  • En pyydä kaikkea dokumentoimaan. Sen pitäisi olla riittää antamaan korkean tason yleiskatsauksen järjestelmän ja koodin toiminnasta. Esim. Kerro minulle, miten televisiota käytetään. En välitä ’, jos se käyttää LCD-näyttöä, CRT: tä, Tyhjiöputket tai SSD-laitteet työn suorittamiseksi . Jos korjausmies haluaa kyseisiä tietoja, tee hänelle erillinen dokumentaatio.
  • Jos haluat korkean tason yleiskatsauksen, tunnisteiden nimet riittävät. Aivan kuten television painikkeessa voi olla ” On ” -tunniste. Joten pyydät matalan tason yksityiskohtia.
  • @LeopoldAsperger: Mielestäni Borat puhuu arkkitehtuurin ja suunnittelun dokumentoinnista, ei luokkien menetelmistä.

Vastaa

Sähköpostiosoitettasi ei julkaista. Pakolliset kentät on merkitty *