ugrás a tartalomhoz

Doc1st, dokumentum-vezérelt fejlesztés

Török Gábor · 2011. Jún. 13. (H), 16.23

A múlt heti budapesti Agilis meetupon tartott előadást Vég Csaba az általa kidolgozott Doc1st (Document First) fejlesztési módszertanról és hozzá kapcsolódó eszközről. A Doc1st a Test-Driven Development (tesztvezérelt fejlesztés) elgondolásán alapul, azt bővíti ki. A Doc1st lényege, hogy a fejlesztést a dokumentáció írásával kezdjük. Ahogy a TDD-vel tulajdonképpen a felhasználói eseteket, peremfeltételeket fektetjük le kódként megfogalmazva, addig Doc1st esetén magát a követelményt, a use case-t fogalmazzuk meg és illesszük be a kódba emberi nyelven megjegyzésként.

A koncepció saját jelölési szinteket definiál, így lehetőség van a kódból különböző nézetek szerint generálni a dokumentációt, így az átfogó, csak a nagyobb rendszer komponensek leírását tartalmazó kivonattól kezdve akár API referencia mélységű felhasználói kézikönyvet is kinyerhetünk. A Doc1st projekt egyelőre kísérleti stádiumban van, a JUnit keretrendszerhez érhető el kiegészítésként. Képes jelezni azt, ha adott funkció dokumentálatlan, és a dokumentumációk meglétéből a fejlesztés készültségére vonatkozólag is visszaad statisztikát.

Mindenféleképpen érdekes az elgondolás, Document Driven Development kifejezéssel már értekeztek róla többen is. Különösen izgalmas lehet a módszer olyan környezetekben, ahol a dokumentáció maga is nyelvi elem (Python, Lisp), és a dokumentációkban elhelyezett teszt esetek kezelésére kiforrott eszköz áll a rendelkezésre (import doctest).

 ■
1

Ertetlenul allok az egesz elott...

saxus · 2011. Jún. 14. (K), 00.13
Lehet, velem van a baj, de nem latom az egesznek sem a celjat, sem az okat, ami eletre hivta ezt.

En is szoktam hasonlokat csinalni, amikor kodvazlatot keszitek masoknak. De ezek csak vazlatok a reszletesebb leirast a funkcionalis specifikaciobol meg tudja irni barki. (Persze, hozzateve a hasznalt kornyezethez szukseges infokat).

Viszont amit itt latok, az a leghorrorisztikusabb kommenteles: gyakorlatilag felesleges, redundans zaj, semmi plusz informaciot nem hordoz ahhoz kepest, ami a kodban is le van irva. Ha meg mar a kommentet leirom, le tudom irni egybol a kodot is.

A masik dolog: az API referenciakkal az a bajom, hogy onmagaban keves kodban meg nehol felesleges zaj. Egy komolyabb - pl. MSDN szintu - API referencia osszeallitasa a kodban nehezkes es sok zavaro elemet termel a kodba. Pl. egy PHPDoc eseten is, sokkal jobb egy rovid, nehany soros osszefoglalot irni, hogy mire is szolgal, maximum a legfontosabb dolgokra kell felhivni a figyelmet. A reszletesebb dolgokat meg valahova mashova kiszervezni.

Ellenben, amit sokkal-sokkal inkabb bele kellene venni a jo kommentalasba az az, hogy egy adott modositas/megvalositas miert es miert ugy szuletik (nalunk pl. szabaly, hogy ha bugfixel valaki, akkor kommentben jelezze, hogy hol mit javitott + ha van, akkor redmine ticket szama.). Ezekrol viszont senki nem beszel, senki nem ad ra ajanlasokat, mindenki csak a nyilvanvalot akarja meginnovalni.

De ha mar szoba hoztam a kommentelest: utobbi idoben ugy erzem kisse elszaporodtak a kulonfele kommentekben es/vagy meta infokban (annotaciok, tagek, hol epp mi a neve) hordozott plusz informaciok. Egyfelol nem rossz eszkozok ezek, de idonkent ez a sok plusz informacio mar a kodolasban zavar. Nem is olyan reg a Visual Studiohoz kerestem is eszkozt, amivel ki/be kapcsolhatoak a kommentek megjelenitese. (Off: (PDT) Eclipse-hez nem tud vki hasonlot?) Egy ido utan zavarova valik, hogy az ember atnezne mondjuk egy osztalyban az adattagok listajat es ahelyett, hogy latja egy kepernyon az osszeset, azt latja, hogy a kepernyon kifer ketto-harom, a maradek helyet mindenfele komment meg annotacio tolti ki, amely az adott pillanatban nem erdekel senkit.

Viszont, ha ez a jovobeli irany, akkor szerintem surgosen at kell gondolni a hasznalt eszkozoket is. (Otletek: ki/be kapcsolhato nezetek, Word szeru oldalt bubborekos kommenteles, stb.)

Szerk: de nem mondom azt, hogy nem vagyok meggyozheto a modszer hasznossagarol, csak akkor valaki tenyleg magyarazza el, hogy mire jo ez es mi szukseg van erre?
2

+1

inf · 2011. Jún. 14. (K), 04.42
Én sem lelkesedem túlzottan ettől a komment ártól. (lol ez szóviccnek is jó volna)

Egy ido utan zavarova valik, hogy az ember atnezne mondjuk egy osztalyban az adattagok listajat es ahelyett, hogy latja egy kepernyon az osszeset, azt latja, hogy a kepernyon kifer ketto-harom, a maradek helyet mindenfele komment meg annotacio tolti ki, amely az adott pillanatban nem erdekel senkit.

Detto, ugyanez szokott lenni a bajom nekem is. A kedvencem, amikor van egy pár soros metódus, hozzá 30 sor commenttel, ami azt magyarázza, hogy mit csinál. Én annak a híve vagyok, hogy a metódus neve majd megmondja, hogy mit csinál, comment meg csak minimális kell, olyan esetekre, ahol zavar van az erőben, és nem teljesen érthető a kód első ránézésre. (Nyilván ez a nézet nem tartható minden esetben.)

Viszont, ha ez a jovobeli irany, akkor szerintem surgosen at kell gondolni a hasznalt eszkozoket is. (Otletek: ki/be kapcsolhato nezetek, Word szeru oldalt bubborekos kommenteles, stb.)


A word szerű szövegbuborékos kommentelés szerintem nagyon jó ötlet.
3

code folding és társai

hector · 2011. Jún. 14. (K), 10.25
Engem egyáltalán nem zavarnak a kommentek, mivel egyrészt be van kapcsolva a code folding, másrészt ha mondjuk egy konkrét függvényhez akarok ugrani, akkor azt többnyire ctags támogatással teszem. De valószínűnek tartom, hogy az is megoldható (vim), hogy csak a kommentezést rejtsem el, ha úgy akarom. Ennek abszolút nem szabad gondot okoznia.
4

Elsiklottál a lényeg felett

saxus · 2011. Jún. 14. (K), 10.49
Ezek az eszközök máshol is megvannak. Nem ezekkel van bajom, hanem, hogy ettől függetlenül minden komment, annotáció és hasonló plusz zaj a kódban, ami egy idő után akár már nagyon zavaró is tud lenni, ha csak kódolni akarok. És most ne olyan kódra gondolj, ahol mondjuk mondjuk 40 kódsorra jut 1-2 komment, hanem olyanra, amit tényleg meg kell tűzdelni kommentekkel és mondjuk 1-5 kódsorra jut 1-2 komment átlagosan.

Vagy nézd meg a doc1st példakódjait, gyakorlatilag elveszik a kód a sok rizsa között:
##kukac##RunWith(Doc1st.class) 
public class _Circle { 
 
  @Test public void _test(){ 
  // The `Circle` class represents a circle of a given radius (`r`) 
  // A `Circle` can be created giving the radius 
    Circle c=new Circle(2); Assert.equals(c.getR(),2.0); 
  // A default `Circle` has 0 radius 
    c=new Circle(); Assert.equals(c.getR(),0.0); 
  // The radius can also be set (`setR`) 
     c.setR(3); Assert.equals(c.getR(),3.0); 
  // The area of the circle is `r*r*PI`, that can be get (`getArea`)  
    Assert.equals(new Circle(2).getArea(),2*2*Math.PI); 
  // A circle can be magnified (`magnify`) by a given factor  
    //c=new Circle(1.5); c.magnify(2); Assert.equals(c.getR(),3.0); 
    // After the `magnify` operation, the area changes to its square 
      //double area=c.getArea(); c.magnify(3); Assert.equals(c.getArea(),3*3*area); 
  } 
 
}
(Hasonló okok miatt állítok már minden IDE-mben valamilyen világosabb háttérszínt a kommenteknek, csak jobban elkülönüljön a komment és a kód egymástól. Tény, hogy ez is plusz zajforrás, de legalább egyértelmű.)
5

TDD->BDD

lexandro · 2011. Jún. 14. (K), 11.25
Ez az agyondokumentálás a következő problémákat veti fel:
  • Ha változik a követelmény, akkor változik a kód és változtatnod kell a dokumentáción is. Ha ezt a dupla munkát nem végzed el, akkor a doksid értéke rohamosan közelít a nullához, mivel out of date lesz, majd onnan villámgyorsan eljutunk a törött ablakokig.
  • A komment - hacsak nem valami széles körben használt framework-ről van szó, mint pl. spring - NEM AD értéket a kódhoz. A TDD azt mondja: test as documentation és csak a legszükségesebb esetekben támogatja a kommentezést, ahol valami nehezebben átlátható dolog történik. A TDD kimondottan ellene van a túlzott dokumentálásnak.
  • Ha a clean code elveket követjük, akkor a single responsibility okán ici-pici osztályokat készítünk, és 10, maximum 15 soros metódusokat, amik könnyen átláthatóak és beszédes nevük van. Ha én valakinél int i; deklarációt látok, elsőre még nem kiabálom le a haját, de már akkor is csúnyán nézek. Minden változó, metódus, konstans és egyéb elem a nevében le kell írja a funkcióját és a saját absztrakciós szintjén meg az osztályon belül is a single responsibility-nek meg kell hogy feleljen.
  • A sok doksi közt elvész a kód. A developer rohangál ide-oda a kommentekben mire talál valami értelmeset:
    
// A default `Circle` has 0 radius   
c=new Circle(); Assert.equals(c.getR(),0.0);
    Ezt minek ledokumentálni?! a getR helyett használj egyrészt getRadius()-t, mert az jobban elmondja mit csinál, másrészt maga a kód olvashatóbbá válik. A felette írt komment haszontalan zaj. Főleg ha valami okból kifolyólag hirtelen a 0.0 átalakul 0.5-e de elfelejtik frissíteni. Márpedig a dev egy büdös, lusta disznó. Minél hamarább elfogadjuk ezt a tényt, annál kevesebb csalódás ér. :-)

Ha már le akarod írni a kód viselkedését, akkor használj BDD-t, amit a nagyok csak úgy definiálnak, mint a jól csinált TDD. Én pl. JBehave-vel annotációkban leírom az elvárt acceptance criteria-kat - de a Cucumber is igen jó erre a célra, és sokkal olvashatóbb - egyeztetem a business analyst-tel és a QA-val, aztán optimális esetben pair programming-ben implementálok egy QA-val vagy egy devvel. Ha minden teszt szépen futogat, akkor oda tudok állni a BA elé, hogy kész a user story, és lehet sign-off-olni, és ő nem tud belekötni, hogy olyan funkció hiányzik, amit ő követelt.

Ne a kódot dokumentáld, hanem az elfogadási kritériumokat (ez de ronda így lefordítva baszki...), mert a legelső és legfontosabb dolog mindenek felett: olyan rendszert szállítani a megrendelőnek határidőre, amit kért.

Ez a dokumentálásos dolog visszalépés az időben olyan 5÷10 évet és szinte SSADM/waterfall szaga van.