Arendajad Miks sa ei tohiks dokumentatsiooni jätta

Mobiilirakenduste, veebirakenduste, töölauarakenduste või JavaScripti raamatukogude arendusvaldkonnas on dokumentatsioonil oluline roll, mis võib määrata kindlaks tarkvara arengu. Aga kui te olete kunagi dokumentatsiooni teinud, nõustute minuga, et arendajate jaoks on see kõige vähem lemmik.

Erinevalt kirjutamiskoodist (mis on see, mida arendajad on allkirjastanud) peab dokumentatsioon (mida me ei teinud) olema ja peaks olema kergesti seeditav kõigile. Tehniliselt peame masinkeelt (koodi) tõlkima inimesele arusaadavasse keelde, mis on karmim kui kõlab.

Kuigi see võib olla tõeliselt koormav, on dokumentatsiooni kirjutamine oluline ja annab eeliseid oma kasutajatele, oma kolleegidele ja eriti endale.

Hea dokumentatsioon aitab kasutajatel

Dokumentatsioon aitab lugejal mõista, kuidas kood toimib, ilmselt. Kuid paljud arendajad teevad vea eeldades, et tarkvara kasutajad on valdavad. Seega võib dokumentatsioon olla õhuke materjal, jättes vahele palju olulisi elemente, mida see algusest peale oleks pidanud sisaldama. Kui te olete selles keeles oskuslik, saate oma asjadest aru saada; kui sa ei ole, siis olete kadunud.

Kasutajatele mõeldud dokumentatsioon koosneb tavaliselt praktilisest kasutusest või “kuidas”. Üldiste kasutajate dokumentatsiooni koostamisel on rusikareegel see peaks olema selge. Inimeste sõbralike sõnade kasutamine on parem kui tehnilised terminid või žargoon. Väga teretulnud on ka reaalse kasutamise näited.

Hea paigutusega disain aitaks kasutajatel ka dokumentatsiooni iga osa skannida ilma silmade pinguta. Mõned head näited (teise nimega minu lemmikud) on dokumentatsioon Bootstrap ja WordPress ' “Esimesed sammud WordPressiga”.

See aitab teisi arendajaid liiga

Igal arendajal on oma kodeerimise stiil. Aga kui tegemist on meeskonnaga töötamisega, peame sageli jagama koode teiste meeskonnaliikmetega. Seega on see oluline konsensuse saavutamine hoida kõiki samal lehel. Nõuetekohaselt kirjutatud dokumentatsioon oleks viide meeskonna vajadustele

Kuid erinevalt lõppkasutaja dokumentatsioonist kirjeldatakse tavaliselt neid dokumente tehnilised menetlused nagu koodide nimetamise konventsioon, mis näitab, kuidas konkreetsed leheküljed tuleb ehitada ja kuidas API töötab koos koodinäidetega. Sageli peaksime ka dokumendi kirjutama koos koodiga (nn kommentaarid) kirjeldamaks, mida kood teeb.

Lisaks sellele, kui teil on uued liikmed oma meeskond hiljem, see dokumentatsioon võib olla aeg tõhus viis neid koolitada, nii et sa ei pea neile andma koodi 1.

Kummaliselt aitab see ka kooderit

Kodeerimise naljakas asi on see, et mõnikord isegi arendajad ise ei mõista koodi, mida nad on kirjutanud. See kehtib eriti juhtudel, kui koodid on jäänud puutumatuks kuudeks või isegi aastateks.

Järsk vajadus vaadata koodid ühel või teisel põhjusel jätaks ühe mõtlema, mis nende mõttes nende koodide kirjutamisel toimub. Ära ole üllatunud: ma olen selles olukorras olnud. See on täpselt kui ma soovis Olin dokumenteerinud oma koodi korralikult.

Koodide dokumenteerimisega saate oma koodide põhjale kiiresti ja ilma pettumiseta pääseda, säästes palju aega, mida saab kulutada muudatuste tegemiseks.

Mis teeb hea dokumentatsiooni?

Hea dokumentatsiooni ülesehitamiseks on mitmeid tegureid.

1. Ärge kunagi arvake

Ära arva, et teie kasutajad teavad, mida sina teate samuti, mida nad on tahad teada. See on alati parem alustada juba algusest olenemata kasutajate taseme tasemest.

Kui ehitasite näiteks jQuery plugina, võite inspiratsiooni saada SlickJSi dokumentatsioonist. See näitab, kuidas struktureerida HTML-i, kuhu panna CSS ja JavaScript, kuidas käivitada jQuery plugin kõige algtasemel ja näitab isegi täielikku lõplikku märgistamist pärast kõigi nende asjade lisamist, mis on midagi ilmset.

Alumine rida on see, et dokumentatsioon on kirjutatud kasutaja, mitte arendaja mõtlemisprotsessiga. Oma dokumentide lähenemine annab teile parema perspektiivi oma teose korraldamisel.

2. Järgige standardit

Koodiga ühilduva dokumentatsiooni lisamisel, kasutage keelelt oodatavat standardit. Alati on hea mõte kirjeldada iga funktsiooni, muutujaid ja funktsiooni poolt tagastatud väärtust. Siin on näide heast inline dokumentatsioonist PHP jaoks.

 / ** * Lisab kohandatud klassid kehaklasside hulka. * * @param array $ klass Kere elemendi klassid. * @return array * / function body_classes ($ klassid) // Lisab rohkem kui 1 avaldatud autoriga blogidele grupi-blogi. kui (is_multi_author ()) $ class [] = 'group-blog';  naasta $ klassid;  add_filter ('body_class', 'body_classes'); 

Järgnevalt on mõned viited inline dokumentatsiooni vormistamiseks parimate tavade kohta PHP, JavaScript ja CSS:

• PHP: PHP dokumentatsiooni standard WordPressile
• JavaScript: UseJSDoc
• CSS: CSSDoc

Kui kasutate SublimeTextit, soovitaksin installida DocBlockr'i, mis eelistatult sisestab teie koodi inline dokumentatsiooniga.

3. Graafilised elemendid

Kasutage graafilisi elemente, nad räägivad paremini kui tekst. Need meediumid on kasulikud, eriti kui teil on graafilise liidesega tarkvara. Saate lisada näitavaid elemente nagu nooled, ring või või midagi, mis võib aidata kasutajatel välja selgitada, kuhu minna sammude tegemiseks ilma arvata.

Järgnevalt on toodud näide torni rakendusest, kus saate inspiratsiooni saada. Nad selgitavad tõhusalt, kuidas versioonikontroll toimib meeldivalt, mis muudab selle mõistetavamaks kui lihtteksti käsurea kasutamine.

4. Lõikamine

Võite kaaluda mõnede asjade lisamist dokumentidesse kuuluvate nimekirjade ja tabelite kaudu, kuna see muudab kasutajate pikema sisu hõlpsamaks skaneerimise ja lugemise.

Lisage sisu tabel ja jagage dokumendid kergesti seeduvatesse osadesse, säilitades siiski iga osa asjakohase sellega, mis järgneb. Hoidke see lühike ja arusaadav. Allpool on näide ilusti organiseeritud dokumentidest Facebookis. Sisukord näitab meid, kuhu soovime klõpsuga hüpata.

5. Muuda ja värskenda

Lõpuks vaadake läbi vead puudutav dokumentatsioon ja vaadake vajadusel läbi või vajadusel ja alati, kui toode, tarkvara või raamatukogu on oluliselt muutunud. Teie dokumentatsioon ei oleks kellelegi kasulik, kui seda ei uuendata regulaarselt teie tootega.