Kodėl dokumentai yra svarbūs ir kodėl turėtumėte juos įtraukti į savo kodą

Programinės įrangos kūrimo srityje yra gausybė akronimų. PARUOŠK, SAUSAI, KIETAI ... ir taip toliau, ir taip toliau. Tačiau kai reikia dokumentuoti ar komentuoti kodą, nėra paprastos frazės.

Kodėl taip yra?

Dokumentacija kūrėjui turėtų būti tokia pat svarbi, kaip ir visi kiti kūrimo aspektai

Šiame straipsnyje aš pasiginčysiu, kodėl dokumentavus kodą tapsite geresniu kūrėju ir prisidėsite prie to, kad esate puikus komandos narys.

Ar niekas tam neturi laiko

Pagrindinė priežastis, kodėl kodas nėra dokumentuojamas, yra dėl laiko.

Kurdami funkciją, kurią reikia užbaigti per tam tikrą laiką, retai kada turime laiko viską sustabdyti ir sutelkti dėmesį į savo kodo dokumentavimą.

Be to, kad suprojektuotume ir parašytume patį kodą, mes taip pat turime atlikti kodo peržiūras, automatikos testus ir pridėti vieneto testus (norėdami paminėti keletą dalykų). Dokumentacija beveik neįtraukta į lygtį.

Tai yra mažiausiai apgalvota detalė, galinti padaryti didžiausią įtaką ateityje.

Nesvarbu, ką vystote, yra tikimybė, kad kada nors jums ar vienam iš jūsų kolegų teks dar kartą tai peržiūrėti. Kai ateis ta diena, jūs taip ryškiai neprisiminsite, ką ir kodėl parašėte.

Ir jei jūs atsimenate, gali būti keletas svarbių atvejų ar konkrečių naudojimo būdų, kurie gali būti neaiškūs. Akivaizdus sprendimas yra dokumentacija .

Jei skirsite papildomą laiką tinkamam aprašymui, ką dirbote, ateityje sutaupysite daug laiko.

Kitą kartą, kai kas nors nori suprasti, kas vyksta jūsų kode, jums tereikia nurodyti jį į dokumentaciją. Tai sutaupys jums laiko, nes jums nereikės aiškinti dalykų ir sutaupysite laiko jiems, nes jie nebus nuo jūsų priklausomi.

O kai tu, kaip kūrėjas, turi ką nors suprasti apie tam tikrą kodavimo aspektą, ką tu darai?

? Einate į dokumentaciją?

Geram kodui nereikia dokumentacijos

Taip, aš žinau, aš žinau ... gerai parašyto kodo, kuris yra glaustas ir gerai apgalvotas, nereikia dokumentuoti. Tai skamba kaip istorija .

Nors taip gali būti, tai neatmeta poreikio pateikti dokumentus ir štai kodėl:

  1. Mes per daug gerai žinome kodo, kurį sudaro funkcija, tvirtumą. Pažvelgus į vieną kodo skyrių, gali neaišku, ar yra kitų skyrių, kurie yra su juo glaudžiai susiję.
  2. Kiekviena jūsų sukurta paslauga turi unikalią API. Rašant, kaip naudoti tą API, reikalinga dokumentacija, kurią galima perskaityti už kodo ribų. Nenorite išpūsti pačios klasės informacijos, kaip naudoti API.
  3. Bendradarbiai, dirbantys skirtinguose skyriuose (kurie galbūt nėra kūrėjai), gali norėti suprasti, ką jūs padarėte ir kaip tai veikia.
  4. Tiesiog pats veiksmas gali paskatinti kitaip žiūrėti į parašytą kodą. Paaiškinę, ką veikia jūsų kodas, priversite įvertinti jo pagrįstumą ir galbūt apsvarstyti galimybę pakeisti dalykus, jei jie neatitinka jūsų lūkesčių.
  5. Dėl palikuonių

Kaip parašyti gerą dokumentaciją

Gera dokumentacija yra tarsi geras kodo blokas. Trumpas, paprastas ir lengvai suprantamas. Štai kelios gairės, kurių galite laikytis:

  • Suprasti, kam skirta dokumentacija. Ar tik kūrėjams? Ar yra platesnė auditorija? Tai suprasdami sutaupysite laiko, nes iš anksto žinosite, kiek paaiškinti savo paaiškinimuose.
  • Parašykite trumpą, bet aprašomąjį pagrindą, paaiškindami pagrindinius dalykus, kuriuos sukūrėte. Tai padės skaitytojams suprasti funkcijos paskirtį ir išsiaiškinti jos svarbą tam, ką jie nori žinoti.
  • Išvardinkite ir aprašykite pagrindines savo funkcijos perspektyvas, būtinai nurodydami visas priklausomybes, egzistuojančias su kitomis funkcijomis.
  • Įsitikinkite, kad yra laiko žyma, kad skaitytojai galėtų pasakyti dokumento galiojimą. Be to, jei naudojate tam tikras bibliotekas, būtinai įtraukite ir jų versijas.
  • Būkite dosnus savo kodavimo pavyzdžiais, išsamiai aprašydami, kaip tinkamai naudoti parašytą funkciją, ir pademonstruokite laukiamus rezultatus.

Pavyzdžiai

Norėdami geriau suprasti, kaip atrodo gera dokumentacija, apžvelgsime keletą puikių pavyzdžių: „Mozilla“ kūrėjų tinklas (MDN), „Django“ ir „Stripe“.

MDN dokumentuose galite aiškiai pamatyti, kad kiekvienas puslapis prasideda trumpu paaiškinimu apie temą.

Tada toliau aprašomi naudojimo atvejai ir metodai. Galiausiai, jis parodo, kurios naršyklės yra suderinamos su šia funkcija, ir pateikia nuorodas į atitinkamą medžiagą.

Django dokumentacija yra labai patikima. Nesvarbu, koks yra jūsų kodavimo lygis, jie padės jums apžvelgti ir mokyti.

Tada jie pereina kiekvieną dalyką, kruopščiai jį detalizuodami, pateikdami trumpus ir glaustus kodo fragmentus, kurie parodo, ką reikia padaryti

Tikiuosi, kad man pavyko pabrėžti dokumentų svarbą ir daviau patarimų, kaip pradėti dokumentuoti savo kodą. Jei turite idėją dėl dokumentų santrumpos, nedarykite tai žemiau pateiktose pastabose.

Gal KID - K EEP T D ocumented?

Jei jums patiko šis straipsnis, plokite, kad ir kiti galėtų juo mėgautis! ???