Cum se face documentația pentru cod și de ce software-ul (adesea) este slab documentat?

Cum se documentează codul?

Aveți deja un indiciu: uitați-vă la modul în care este documentat Java API.

Mai general, nu există un set unic de reguli care să se aplice fiecărui proiect. Când lucrez la proiecte de anvergură critice pentru afaceri, documentația nu are nimic de-a face cu cea pe care aș scrie-o pentru o mică bibliotecă open source, care, la rândul său, nu are nimic de-a face cu documentația proiectului meu personal la scară medie. .

De ce multe proiecte open source nu sunt bine documentate?

Deoarece majoritatea proiectelor open source sunt realizate de oameni care contribuie la aceste proiecte pentru că este distractiv. Majoritatea programatorilor și dezvoltatorilor consideră că scrierea documentației nu este suficient de distractiv pentru a fi făcut gratuit.

De ce multe proiecte cu sursă închisă nu sunt bine documentate?

Deoarece costă o sumă imensă de bani să (1) scrii o documentație bună și (2) să o întreții.

1. Imediat costul (costul redactării documentației) este vizibil în mod clar pentru părțile interesate: dacă echipa dvs. cere să petreacă următoarele două luni documentând proiectul, sunt două luni suplimentare de salariu de plătit.

2. Lo Costul pe termen lung (costul întreținerii documentației) devine vizibil destul de ușor și pentru manageri și este adesea prima țintă atunci când trebuie să reducă costul sau să reducă întârzierile. Acest lucru cauzează o problemă suplimentară a documentației învechite, care devine rapid inutilă și este extrem de costisitoare de actualizat.

3. Economiile pe termen lung (economii datorate faptului că nu trebuie să pierdeți câteva zile explorând codul vechi doar pentru a înțelege un lucru de bază care ar fi trebuit documentat cu ani în urmă) sunt, pe de altă parte, dificil de măsurat, ceea ce confirmă sentimentul unor manageri că scrierea și întreținerea documentației este o pierdere de timp.

Ceea ce observ adesea este că:

1. La început, echipa este dispusă să documenteze multe.

2. În timp, presiunea termenelor și lipsa de interes fac din ce în ce mai dificilă întreținerea documentației.

3. Câteva luni mai târziu, o persoană nouă care se alătură proiectului practic nu poate „utiliza documentația, deoarece nu corespunde deloc sistemului actual.

4. Observând că managementul dă vina pe dezvoltatori pentru neîntreținerea documentației; dezvoltatorii cer să petreacă câteva săptămâni actualizându-l.

   • Dacă managementul acordă câteva săptămâni pentru asta, ciclul se repetă.

   • Dacă managementul refuză, pe baza experienței anterioare, aceasta crește doar experiența proastă, deoarece produsul nu are documentație, dar s-au petrecut câteva luni scriind-o și întreținând-o.

Documentarea ar trebui să fie un proces continuu, la fel ca testarea. Petreceți o săptămână pur și simplu codificând câteva mii de LOC și revenirea la teste și documentare este foarte, foarte dureroasă.

Cum să încurajați echipa să scrie documentație?

În mod similar cu modalitățile de a încuraja oamenii să scrie cod curat, să facă refactorizare regulată, să folosească modele de proiectare sau să adauge suficiente teste unitare.

• Condus de exemplu. Dacă scrieți o documentație bună, s-ar putea ca și perechile dvs. să înceapă să o facă.

• Efectuați recenzii sistematice de coduri, inclusiv recenzii oficiale de coduri care vizează inspectarea documentației.

• Dacă unii membri ai echipei sunt deosebit de antipatici față de o bună documentare (sau chiar deloc documentare), discutați subiectul cu ei în mod privat, pentru a înțelege care sunt impedimentele care îi împiedică să scrie o documentație mai bună. Dacă dau vina pe lipsa de timp, vedeți sursa problemelor.

• Faceți prezența sau lipsa documentației măsurabile pentru câteva săptămâni sau luni, dar nu faceți acest lucru. De exemplu, puteți măsura numărul de linii de comentarii pe LOC, dar nu o faceți o măsură permanentă, altfel dezvoltatorii vor începe să scrie comentarii lungi, dar fără sens, doar pentru a scăpa de scorurile scăzute.

• Utilizați gamificarea. Acest lucru vine împreună cu punctul anterior.

• Utilizați pozitiv / negativ armare .

• (Consultați comentariul SJuan76 ) Tratați lipsa comentariilor ca erori. De exemplu, în Visual Studio, puteți verifica o opțiune pentru a genera documentație XML. Dacă verificați și dacă toate avertismentele sunt tratate ca erori, lipsa unui comentariu în partea de sus a unei clase sau a unei metode va opri compilarea.

  În ceea ce privește cele trei puncte anterioare, acesta ar trebui să fie utilizat Cu grijă. L-am folosit o vreme cu o echipă deosebit de dură de programatori pentru începători și a ajuns la comentarii conforme cu StyleCop de genul:

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

care, hm …, nu erau deosebit de utile.

Amintiți-vă: nimic automatizat nu vă poate ajuta să identificați comentariile proaste atunci când programatorii doresc să vă descurce . Numai cod recenziile și alte sarcini umane vă vor ajuta.

Există exemple bune de când este necesară sau nu este necesară nicio documentație?

Documentația care explică arhitectura și designul nu este necesară:

• Pentru un prototip,

• Pentru un proiect personal scris în câteva ore pentru a realiza o sarcină, fiind în același timp sigur că acest proiect nu va mai fi menținut,

• Pentru orice proiect în care este evident, având în vedere dimensiune redusă a acestuia, împreună cu codul deosebit de curat, că veți petrece mai mult timp scriind documentație decât toți viitorii întreținători care explorează codul.

Documentația în cod (comentarii de cod) nu este necesară conform unor dezvoltatori atunci când codul se autodocumentează. Pentru ei, prezența comentariilor nu este, cu excepția cazurilor rare, un semn bun, ci un semn că codul nu a fost refactorizat suficient pentru a fi clar fără a fi nevoie de comentarii.

Cred că ar trebui să avem o revizuire a documentației după livrarea unui proiect.

Dacă proiectul dvs. este livrat cel puțin o dată pe săptămână, este calea de urmat. Dacă proiectul dvs. nu este agil și este livrat la intervale de șase luni, atunci efectuați recenzii mai regulate.

Comentarii

• Pentru a cum să încurajați ‘, aș adăuga că multe IDE permit notificarea documentelor lipsă ca avertismente. Alternativ, poate că o analiză statică a documentației se poate face la OSB (desigur, numai asta nu ar fi suficient).
• @ SJuan76: Într-adevăr. Visual Studio poate trata chiar și lipsa de comentarii ca o eroare în timpul compilării. Mi-am editat răspunsul pentru a adăuga o notă despre asta.
• @ArseniMourzenko – Am citit că am putea încuraja unele documente în Agile adăugând povești pentru documentare. Dar, acestea nu ar trebui să blocheze celelalte povești, adică definiția altor povești de făcut, nu trebuie să includă completarea poveștilor de documentare. Cum sună asta?
• @ArseniMourzenko – Aș dori să adaug încă două puncte la răspunsul dvs. ‘ (1) În Jira etc., adăugați o sarcină pentru documentare tot timpul. (2) Solicitați documentelor revizuite de încă 2 persoane & puneți acest lucru și ca o sarcină. În acest fel, oamenilor li se va reaminti documentul & va evita să scrie documente de calitate scăzută (datorită examinării). Dacă nu ‘ îl acordați prioritate &, examinați-l, atunci va deveni rău. Știu că Amazon face o mulțime de documente & recenzii de documente, poate cam prea mult.

Cred că ar trebui să faceți o distincție între comentarii și documentație. În timp ce comentariile sunt descriptive, nu au consistență, sunt împrăștiate în tot codul. Comentariile nu ar trebui să compenseze niciodată codul care nu se autodescrie suficient, ci ar trebui să sugereze alți programatori la părți dificile.

Dacă codul trebuie documentat depinde de amploarea proiectului. Cu siguranță există oameni care cred că tot ceea ce ar trebui documentat și pare ușor să justifice acest gând, pentru că cine ar îndrăzni să se opună documentarea cunoștințelor? Din fericire, dezvoltarea software-ului nu este știință, iar lumea nu se prăbușește dacă detaliile din spatele micului dvs. program devin obscure. În ceea ce privește un software profesional pentru a fi utilizat de mulți dezvoltatori, da, evident, ar trebui să vă documentați codul. pentru a codifica la acel nivel, atunci știți clar că.

tl; dr

Dacă solicitați ca fiecare proiect să fie bine documentat, atunci veți cere prea mult .

Comentarii

• Fortunately software development is not science Vă rog să-mi spuneți mai multe despre motivul pentru care credeți acest lucru.
• @Borat – Dezvoltarea software-ului este o disciplină de inginerie, ceea ce implică faptul că folosește instrumentele furnizate de știința.
• Nu cer să fie documentat totul. Ar trebui să fie suficient pentru a oferi o imagine de ansamblu la nivel de ceea ce face un sistem și cod. De exemplu, vă rog să-mi spuneți cum să folosesc televizorul meu. Nu îmi pasă dacă divizează LCD, CRT, Tuburi de vid sau dispozitive în stare solidă pentru a face treaba . Dacă un reparator dorește aceste informații, atunci faceți documentație separată pentru el.
• Dacă doriți o imagine de ansamblu la nivel înalt, atunci numele identificatorilor sunt suficiente. La fel cum butonul de pe televizor ar putea avea o etichetă ” pe „. Așadar, solicitați detalii la nivel scăzut.
• @LeopoldAsperger: Cred că Borat vorbește despre documentarea arhitecturii și proiectării, nu a metodelor din clase.