Azt hittem, már valami alter irányzat kezdett kibontakozni clean code-nak csúfolva magát.
Valószínűleg az én angol tudásom kopott meg, de ebben sem látom a tiltást. Persze kiemelhetném a "not to write" kifejezést az egészből, és ignorálhatnám az ezt körbevevő bekezdések tartalmát, de miért is tennék ilyet!
Szerintem érdemes elolvasni a teljes fejezetet, ha még nem tetted meg. Különösen azokat a részeket, ahol azt ecseteli például, hogy totálisan felesleges leírni a kód mellé/alá/fölé, hogy mit csinál, mert az olvasó ezt amúgy is látja, viszont például azon ritka esetekben, amikor a miért kérdésre adandó választ kívánja megörökíteni a fejlesztő, a mögöttes szándékot, amit semmilyen más nyelvi eszközzel nem lehetne egyszerűen megmutatni, akkor érdemes ezt megtenni, hogy megkönnyítsük az olvasó dolgát. Persze a gányolást is lehet kommentben magyarázgatni, de a könyv többi része azt szajkózza, hogy ne gányolj, szóval...
Az általad idézett "not to write" arról beszél, hogy ha szépen írod meg a kódot, akkor a kommentek elhelyezése is szükségtelenné fog válni, mivel feltételezzük, az olvasó tud alapszinten jávául és minden szükséges információt megkap a konstansok, változók, metódusok és osztályok elnevezéseiből, struktúrájából.
Semmi sem fekete vagy fehér, így tudathasadásról sem lehet beszélni, hiszen értjük az ajánlás mögötti szándékot és aszerint cselekszünk. A clean code szerintem meg amúgy sem szabály, hanem ajánlás.
A public api javadoc meg más tészta, az a feladata, hogy röviden összefoglalja a mögöttes funkció lényegét és tájékoztasson a használat módjáról, megspórolva az olvasónak a forráskód böngészését... de erről a többiek is sokat írtak.