Van néhány jó példa a jól dokumentált kódra, például a java api. De sok olyan kód az állami projektekben, mint a git és a vállalatok belső projektjei, kevéssé dokumentált és nem túl újonnan barát.

Valamennyi szoftverfejlesztési munkám során rosszul dokumentált kóddal kellett megküzdenem. A következő dolgokat vettem észre –

  1. Kevés vagy egyáltalán nem fűzött megjegyzést a kód.
  2. A módszer és a változó neve nem írja le önmagát.
  3. Kevés vagy egyáltalán nincs dokumentáció arról, hogy a kód hogyan illeszkedik a rendszerbe vagy az üzleti folyamatokba.
  4. Rossz fejlesztők alkalmazása vagy a jóak mentorálása. Nem tudnak egyszerű és tiszta kódot írni. Ezért bárkinek, beleértve a fejlesztőt is, nehéz vagy lehetetlen dokumentálnia a kódot.

Ennek eredményeként rengeteg dolgot kellett átélnem. kódoljon és beszéljen sok emberrel, hogy megtanulják a dolgokat. Úgy érzem, ez pazarolja mindenki idejét. Ez szükségessé teszi a KT / Tudástovábbítási munkameneteket a projekt újonnan érkezőinek számára is.

Megtudtam, hogy a dokumentáció a következő okok miatt nem kapja meg a megérdemelt figyelmet:

  1. Lustaság.
  2. A fejlesztők nem szeretnek mást tenni, csak kódolni.
  3. Munka biztonsága. (Ha senki sem érti könnyen a kódját, akkor előfordulhat, hogy nem lesz könnyen cserélhető.)
  4. A nehéz határidők kevés időt hagynak a dokumentálásra.

Tehát kíváncsi vagyok, van-e mód arra, hogy ösztönözzük és érvényesítsük a jó dokumentációs gyakorlatokat egy vállalatnál vagy projektnél. felhasználható a projektek rendszereihez és kódjaihoz való megfelelő dokumentáció készítéséhez, tekintet nélkül a bonyolultságára? Van-e jó példa arra, hogy minimális dokumentációra van szükség vagy egyáltalán nincs szükség?

IMHO, úgy érzem, hogy meg kellett volna a projekt átadása után a dokumentáció áttekintése. Ha ez nem egyszerű, tömör, szemléltető és felhasználóbarát, akkor a fejlesztő vagy a műszaki dokumentáció mérnöke felelős a projektért, és meg kell oldaniuk azt. Nem számítok arra, hogy az emberek dokumentációkat készítenek, nem remélem, hogy felhasználóbarát lesz, mint az első könyvek, de remélem, hogy megszünteti a szükségét órányi elemzés és pazarló KT foglalkozások.

Van-e mód ennek az őrületnek a megszüntetésére vagy enyhítésére? Talán “dokumentumvezérelt fejlesztés”?

Megjegyzések

  • Van egy másik oka annak, hogy gyakran nincs megfelelő dokumentáció: Nagyon nehéz olyan jó dokumentációt írni, amely nem ‘ t csak átfogalmazza a kódot angolul, de leírja, hogy miért a kódot így tervezték / írták. Ezeknek az információknak a szükségessége csak hónapok múlva válik nyilvánvalóvá azután, hogy azokat le kellett volna írni.
  • Egy másik komoly ok: sok fejlesztőnek van második nyelve az angol és / vagy rosszul írnak angolul . Lehet, hogy csak arra kényszeríti őket, hogy egy módszerhez egyvonalas vonalat írjanak, de ha jó dokumentációt szeretne, akkor jobban hajlandó fizetni érte, és szakembereket kell felvennie erre.

Válasz

Hogyan kell dokumentálni a kódot?

Már van egy tippje: nézze meg, hogyan dokumentálják a Java API-t.

Általánosabban elmondható, hogy nincs egyedi szabályrendszer, amely minden projektre vonatkozna. Amikor üzleti szempontból kritikus nagyszabású projekteken dolgozom, a dokumentációnak semmi köze ahhoz, amelyet egy kis nyílt forráskódú könyvtárhoz írnék, aminek viszont semmi köze a közepes méretű személyes projektem dokumentálásához. .

Miért nincs sok nyílt forráskódú projekt dokumentálva?

Mivel a legtöbb nyílt forráskódú projektet olyan emberek készítik, akik hozzájárulnak ezekhez a projektekhez, mert szórakoztató. A legtöbb programozó és fejlesztő úgy véli, hogy hogy a dokumentáció megírása nem elég szórakoztató ingyen elvégezhető.

Miért sok zárt forráskódú projekt nincsenek jól dokumentálva?

Mivel hatalmas pénzbe kerül a (1) jó dokumentumok megírása és (2) fenntartása.

  1. Azonnali költség (a dokumentáció megírásának költsége) jól látható az érintettek számára: ha csapata azt kéri, hogy a következő két hónapot a projekt dokumentálásával töltse, akkor további két hónap fizetést kell fizetnie.

  2. A lo A futamidő költsége (a dokumentáció karbantartásának költsége) a vezetők számára is könnyen észrevehetővé válik, és gyakran az első célpont, amikor csökkenteniük kell a költségeket vagy meg kell rövidíteniük a késéseket. Ez az elavult dokumentáció további problémáját okozza, amely gyorsan használhatatlanná válik, és rendkívül költséges frissíteni.

  3. Hosszú távú megtakarítás (megtakarítás, ha nem kell néhány napot pazarolni a a régi kódot csak azért, hogy megértsük az alapvető dolgokat, amelyeket évekkel ezelőtt dokumentálni kellett volna) viszont nehéz mérni, ami megerősíti egyes vezetők azon érzését, hogy a dokumentumok írása és karbantartása időpazarlás.

Amit gyakran megfigyelek:

  1. Kezdetben a csapat hajlandó sokat dokumentálni.

  2. Idővel a határidők nyomása és az érdeklődés hiánya egyre nehezebbé teszi a dokumentáció karbantartását.

  3. Néhány hónap később egy új ember, aki csatlakozik a projekthez, gyakorlatilag nem tudja használni a dokumentációt, mert egyáltalán nem felel meg a tényleges rendszernek.

  4. Ezt észrevéve a vezetőség a fejlesztőket hibáztatja a dokumentáció elmulasztása miatt; a fejlesztők azt kérik, hogy töltsenek néhány hetet a frissítéssel.

    • Ha a menedzsment erre néhány hetet engedélyez, a ciklus megismétlődik.

    • Ha a menedzsment megtagadja, a korábbi tapasztalatok alapján ez csak növeli a rossz tapasztalatokat, mivel a terméknek nincsenek dokumentációi, de néhány hónapot a megírásával és karbantartásával töltöttek.

A dokumentációnak a folyamathoz hasonlóan folyamatos folyamatnak kell lennie. Töltsön el egy hetet egyszerűen néhány ezer LOC kódolásával, és a tesztekhez és a dokumentációhoz való visszatérés nagyon-nagyon fájdalmas.

Hogyan ösztönözzük a csapatot az írásra dokumentáció?

Hasonlóképpen, mint arra ösztönözni az embereket, hogy tiszta kódot írjanak, rendszeresen végezzenek újrakezdést, használjon tervezési mintákat vagy adjon hozzá elegendő egységtesztet. Példa alapján levezetve. Ha jó dokumentációt ír, a párok is elkezdhetik ezt csinálni.

  • Szisztematikus kódellenőrzéseket végezzen, beleértve a dokumentumok ellenőrzésére irányuló hivatalos kódellenőrzéseket is.

  • Ha a csapat egyes tagjai különösen ellenszenvesek a jó dokumentációval (vagy egyáltalán a dokumentációval szemben), akkor privátban beszélje meg velük a témát, hogy megértse, melyek azok az akadályok, amelyek megakadályozzák őket abban, hogy jobb dokumentációt írjanak. Ha az idő hiányát okolják, akkor látja a problémák forrását.

  • Tegye mérhetővé néhány hétig vagy hónapig a dokumentáció jelenlétét vagy hiányát, de ne erre koncentrálhat. Például megmérheti a megjegyzéssorok számát egy LOC-onként, de ne tegye állandó mércévé, különben a fejlesztők hosszú, de értelmetlen megjegyzéseket kezdenek írni, csak hogy megszabaduljanak az alacsony pontszámoktól.

  • Használja a játékot. Ez összeér az előző ponttal.

  • Használjon pozitív / negatív megerősítést .

  • (Lásd SJuan76 megjegyzését ) A megjegyzések hiányát hibaként kezelje. Például a Visual Studio-ban ellenőrizheti az XML-dokumentáció létrehozásának egyik lehetőségét. Ha azt is ellenőrzi, hogy az összes figyelmeztetést hibának tekintik-e, akkor az osztály vagy egy módszer tetején lévő megjegyzés hiánya leállítja az összeállítást.

    Ami az előző három pontot illeti, ezt kell használni óvatosan. Egy ideig egy kezdő programozók különlegesen kemény csapatával használtam, és végül a StyleCop-kompatibilis kommentekkel zárult: 

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

    amelyek, hm …, nem voltak különösebben hasznosak.

    Ne feledje: semmi automatizált nem segíthet a rossz megjegyzések pontos meghatározásában, amikor a programozók veled akarnak csavarozni . Csak kód az áttekintések és más emberi feladatok segítenek.

    Van-e jó példa arra, amikor minimális vagy egyáltalán nincs szükség dokumentációra?

    Az architektúrát és a kialakítást magyarázó dokumentáció nem szükséges:

    • Prototípushoz

    • Olyan személyes projekt esetén, amelyet néhány óra alatt írtak meg egy feladat elvégzéséhez, miközben eléggé biztos abban, hogy ezt a projektet nem fogják tovább fenntartani.

    • Minden olyan projekt esetében, ahol ez nyilvánvaló, a kis mérete, a különlegesen tiszta kóddal párosítva, több időt fog fordítani a dokumentumok írására, mint az összes jövőbeli karbantartó a kód feltárására.

    A kóddokumentációra (kód megjegyzések) nincs szükség egyes fejlesztők szerint, amikor a kód öndokumentál. Számukra a megjegyzések jelenléte, a ritka esetek kivételével, nem jó jel, hanem annak a jele, hogy a kód nem volt eléggé visszafejlesztve ahhoz, hogy egyértelmű legyen kommentek nélkül.

    Úgy érzem, hogy egy projekt átadása után át kell néznünk a dokumentációt.

    Ha a projektjét legalább kézbesítették hetente egyszer, ez a helyes út. Ha a projektje nem mozgékony és hat hónapos időközönként kerül leadásra, akkor végezzen rendszeresebb felülvizsgálatokat.

    Megjegyzések

    • To ‘ hogyan ösztönözhetem ‘, hozzáteszem, hogy sok IDE lehetővé teszi a hiányzó dokumentumok figyelmeztetésként történő értesítését. Alternatív megoldásként talán a dokumentáció statikus elemzése elvégezhető az OSB-n (természetesen ez önmagában nem lenne elég).
    • @ SJuan76: Valóban. A Visual Studio akár a fordítás idejének hibájaként is kezelheti a megjegyzések hiányát. Szerkesztettem a válaszomat, hogy megjegyzést fűzzek ehhez.
    • @ArseniMourzenko – olvastam, hogy ösztönözhetnénk néhány dokumentációt az Agile-ban, ha hozzáadnánk a történeteket dokumentációhoz. De ezek nem akadályozhatják a többi történetet, vagyis a kész más történetek definícióját, nem tartalmazhatják a dokumentációs történetek befejezését. Hogy hangzik ez?
    • @ArseniMourzenko – ‘ szeretnék még két pontot adni a válaszához. (1) A Jirában stb. Adjon meg egy feladatot a dokumentáláshoz. (2) Bármelyik dokumentumot ellenőrizze még 2 ember &, tegye ezt is feladatként. Így emlékeztetni fogják az embereket arra, hogy dokumentálják & kerülni fogják a rossz minőségű dokumentumok írását (felülvizsgálat miatt). Ha nem ‘ nem helyezi fontossági sorrendbe &, akkor rossz lesz. Tudom, hogy az Amazon sok docs & doc felülvizsgálatot végez, talán egy kicsit túl sokat.

    Válasz

    Szerintem különbséget kell tenni a megjegyzések és a dokumentáció között. Míg a megjegyzések leíró jellegűek, hiányzik a következetesség, az egész kódban szétszóródnak. A megjegyzéseknek soha nem szabad kompenzálniuk azokat a kódokat, amelyek nem eléggé leírják önmagukat, ehelyett trükkös részekre kell utalniuk a többi programozóra.

    Az, hogy a kódot dokumentálni kell-e, a projekt méretétől függ. Bizonyára vannak olyan emberek, akik úgy vélik, hogy mindent dokumentálni kell, és könnyűnek tűnik ezt a gondolatot igazolni, mert ki merne ellenkezni az ismeretek dokumentálása? Szerencsére a szoftverfejlesztés nem tudomány, és a világ nem fog összeomlani, ha a kis program mögött rejlő részletek homályossá válnak. Most egy professzionális szoftverrel kapcsolatban, amelyet sok fejlesztő használ, igen, nyilván dokumentálnia kell a kódját. ezen a szinten kódolni, akkor ezt nyilván tudná.

    tl; dr

    Ha azt kéri, hogy minden projekt legyen jól dokumentálva, akkor túl sokat kérjen. .

    Megjegyzések

    • Fortunately software development is not science Kérem, mondja el, hogy miért hiszi ezt.
    • @Borat – A szoftverfejlesztés mérnöki tudományág, ami azt jelenti, hogy az a tudomány által biztosított eszközöket használja.
    • Nem kérek mindent dokumentálni. Meg kell csak annyi, hogy magas szintű áttekintést nyújtsunk arról, hogy mit csinál egy rendszer és a kód. Például. Kérjük, mondja el, hogyan kell használni a tévéimet. Nem érdekel, ha LCD-t, CRT-t használ, Vákuumcsövek vagy szilárdtest-eszközök a munka elvégzéséhez . Ha egy javító ember szeretné ezeket az információkat, készítsen külön dokumentációt neki.
    • Ha magas szintű áttekintést szeretne, akkor az azonosító nevek elegendőek. Ugyanúgy, mint a tévé gombjának ” lehet ” címkéje. Tehát alacsony szintű részleteket kér.
    • @LeopoldAsperger: Úgy gondolom, hogy Borat az építészet és a tervezés dokumentálásáról beszél, nem pedig az osztályokban alkalmazott módszerekről.

    Vélemény, hozzászólás?

    Az email címet nem tesszük közzé. A kötelező mezőket * karakterrel jelöltük