Sokan, különsen a hamariban agile fejlesztési módszereket követő emberkék gondolják azt, hogy dokumentálni nem kell.
Ez nem igaz. Az éppen elegendő dokumentáció sajnos egy elég rosszul megfogalmazott valami. Valójában dokumentálni kell, de a nemtriviális dolgokat. Agile fejlesztők mondják, hogy commentek helyett a program legyen önmagyarázó. Beszéde változónevek, egyszerű struktúra, megfelelő felelősségi kör kiosztás. A gond az, hogy sokszar azt látom én is, hogy leírja mit csinál. Nem tagadom néha szükséges, különsen, ha szinte titkosírásban van írva a kód. De amire egy forráskód dokumentációban szükség van, az az előfeltétel és utófeltétel (pre- és postcondition). Én személy szerint az utófeltételt tartom fontosabbnak, mert az előfeltételt úgy is ellenőrzi az eljárás.
Szóval ha van egy eljárás, akkor ne az legyen leírva, hogy milyen lépéseket halyt végre, hanem azt, hogy mi lesz az eredménye. Ha hiba van, akkor úgy is az algoritmusban a probléma, és abban a pszeudóalgoritmus nem segít, hiszen pont az van leírva, ami hibás. De ha tudjuk, hogy minek kell lenni a végének, akkor pontosan meg tudjuk határozni, hogy mi az elvárt eredmény. Ráadásul ezt akár autómatizálva is lehet tesztelni (Unit Test). Ha használok egy külső api-t, nem érdekel hogyan csinálja, amit csinál, amig azt teszi, amit elvárok tőle, ami az elő- és utófeltételében le van írva.
