"(Write Once, Read Many)" - Deze heb ik nog nooit gehoord in deze context.
Bij deze ;-)
Ik vind em wel lekker beknopt de lange-termijn tijdsbesparing vatten.
Het geldt ook in discussies over de verbosity van code en dingen zoals lange versus korte variabelenamen. De tijd die het kost om je code leesbaar en begrijpelijk te maken verdien je dubbel en dwars terug door de tijd die het je (en alle andere toekomstige lezers) bespaart tijdens het lezen van de code.
In veel gevallen echter als excuus van ontwikkelaars, omdat ze de code niet begrijpen, terwijl collega ontwikkelaars er geen moeite mee hebben.
Tja, dat is niet meer dan een stukje positieve compensatie van genoemde collega-ontwikkelaars. Natuurlijk zijn sommige mensen veel beter in snel een mentaal model opbouwen van een matig gedocumenteerd systeem, maar het lijkt me onjuist om op basis daarvan te impliceren dat er niets mis is met een matig gedocumenteerd systeem.
Volgens dezelfde logica zou je bijvoorbeeld kunnen zeggen dat het prima is om uberhaupt geen lunchpauze te doen omdat sommige mensen prima door kunnen werken zonder een lunchpauze in de dag te hebben.
Terzijde, als general tip voor bekend raken met een codebase: een van de eerste stappen moet imho zijn om alle TODOtjes en FIXMEs van de codebase door te lezen. Dat geeft (gegeven dat ze bestaan) vaak heel veel info over eerdergenoemde eigenaardigheidjes en zwaktes, en over het niveau van haast/genomen shortcuts tijdens de eerdere ontwikkeling.
Incomplete documentatie ...
Mee eens. Ik zei niet voor niets: "
Actuele, goede documentatie en specificatie is belangrijk ...". Het gebeurt meer dan eens dat er initiëel wel tijd gestopt wordt in het schrijven van documentatie tijdens het ontwerpproces, maar dat deze nooit meer wordt aangepast aan de veranderde requirements. Maar dat is (imho) precies waar je wel tijd en geld voor moet vrijmaken om je systeem in brede zin solide te maken.
Vaak kun je dan beter de gebruikershandleiding lezen, die geeft vaak nog het beste beeld van het systeem én is redelijk up to date
En
waarom is de gebruikershandleiding
wel up to date? Het antwoord is dat
iedereen inziet dat een half kloppende gebruikershandleiding waardeloos is en je business schaadt (toegegeven: deels ook omdat er minder technische kennis voor nodig is om de gebruikershandleiding actueel en kloppend te maken). Maar in zekere zin
is de gebruikershandleiding documentatie. Het zijn in principe de use cases van het systeem (zij het met een laag detailniveau van de acties van het systeem).
Code-commentaar is daarbij ESSENTIEEL en in soms nog belangrijker dan systeemdocumentatie.
Ook absoluut mee eens. Hier kan een developer in zekere zin wel de documentatietijd 'opeisen', door die code comments als integraal onderdeel van het schrijven van de code te zien (en zich niet te laten verleiden om e.e.a. z.s.m. de deur uit te willen knallen). Tegelijkertijd valt er nog steeds veel voor te zeggen om tijd in te plannen om de bestaande code door te nemen en daar waar de code comments tekortschieten deze aan te vullen. Waar gehakt wordt vallen spaanders.
Ik wil niet zeggen dat documentatie onnodig is, maar klassieke systeemdocumentatie/ontwerpen zijn zeker niet heilig.
Een van de functies die dergelijke documenten ook hebben is dat ze de hele technische in-depth wereld die de code zelf is in een vorm vatten waarmee ook minder technisch onderlegden het overzicht kunnen krijgen en houden en daardoor betere (tijdsbesparende!) conclusies kunnen trekken en beslissingen kunnen maken over het systeem. Eigenlijk zou het bijvoorbeeld nooit voor moeten komen dat iemand in een support-rol of iemand die nieuwe features of aanpassingen moet voorstellen aan de developers moet vragen/zeggen: "Hoe werkt dit nu eigenlijk?" of "Volgens mij klopt het niet hoe het nu werkt."
Als je nergens anders dan in de code zelf hebt vastgelegd hoe het inderdaad zou moeten werken, dan kun je eigenlijk ook niet vaststellen of de geïmplementeerde werking ook de juiste is (is het by design, of is de implementatie onjuist?). In die zin is het ook een soort vorm van redundancy (zij het dat de specificatie en documentatie in principe altijd leidend zouden moeten zijn).