Az a kellemetlen igazság: a kódbázisod a legjobb dokumentációd

Van egy gondolat, ami minden CTO-nak és lead developernek rosszul kellene hogy essen: a legmélyebb üzleti tudás gyakran sehol máshol nem létezik, csak a production kódban.

Egy friss kutatási anyag provokatív ötlettel áll elő. A szerzők azt állítják, hogy az érett szoftverrendszerek nem egyszerűen eszközök, amelyek a vállalkozást működtetik — hanem végrehajtható lenyomatai mindannak, amit a szervezet az évek során megtanult. A probléma csak az, hogy ez a tudás lappang a szemünk előtt, repository-kban rejtőzik, amelyeket eddig csak compiler-ek és (alkalmanként) emberek olvastak.

A dokumentáció mítosza

Mindannyian átéltük. Új fejlesztő csatlakozik a csapathoz, és kap egy halom Confluence oldalt, architecture decision record-ot, wiki bejegyzést. "Ez majd felhoz az alapokra" — mondja valaki bizakodó hangon.

Nem fogja.

A dokumentáció azt tartalmazza, amit valaki fontosnak gondolt leírni, egy pillanatban, ami évekkel ezelőtt lehetett. Nem tartalmazza az edge case-eket. Nem tartalmazza az érveket, amik a megbeszéléseken elhangzottak és formálták a döntéseket. Nem tartalmazza azt az üzleti logikát, ami évi ezernyi commit során alakult ki, mindegyik egy valós szcenárióval küzdve.

Peter Naur 1985-ös érvelése szerint (igen, az a Naur, aki a Backus-Naur formátumot megalkotta) a program-dokumentáció soha nem tudja teljesen megragadni a rendszer mögötti "elméletet". A valódi megértés az emberek fejében él. Amikor azok az emberek mennek, az elmélet is velük megy.

De itt jön a fordulat.

Az AI megváltoztatja az olvasók szabályait

Naur érvelése kétféle olvasóról szólt: compiler-ek (amelyek értik a kódot, de nem értik a jelentését) és emberek (akik lassan és drágán értik meg). A dokumentáció újjáélesztésének lehetetlensége feltételezte, hogy nem létezik másfajta olvasó.

A nagy nyelvi modellek egy harmadik típusú olvasók. És meglepően jók abban, hogy rekonstruálják a kódba ágyazott implicit elméleteket.

A ServiceMatch rendszere meggyőző bizonyítékot szolgáltat. Az ő CMDB platformjuk vállalati konfigurációs menedzsment tudást kódol — olyan tudást, ami köteteket töltene meg, ha prózában írnák. De itt a lényeg — már meg van írva, csak nem prózában. Hanem kódban.

Vegyük például az identity resolution logikát. Ahelyett, hogy egy konzultáns esszéjét kapnánk arról, hogyan működik az eszköz identitás, van egy konfigurációs fájljuk súlyozással: sorozatszám (25), hostname (25), asset tag (25), IP cím (20), MAC cím (15). És confidence threshold-ok, meg conflict resolution szabályok. Minden szám egy megnyert érv. Minden conflict típus egy valós incidens, ami valahol megtörtént.

Ez nem leírása a policy-nek. Ez A policy, ami éjszakánként fut a valódi vállalati eszközökön.

Mit jelent ez a csapatodnak

Fejlesztőknek és technikai vezetőknek a kutatás gyakorlati következményei vannak:

A kódod olyan dokumentáció, amit nem karbantartottál — és ennek megvannak az előnyei. A szűkös wiki oldalakkal ellentétben a production-ban futó kód folyamatosan validálva van. Ha a dokumentáció és a kód nem egyezik, a dokumentáció téved.

Az AI eszközök egyre jobbak lesznek a tudás kinyerésében. Olyan világ felé haladunk, ahol megkérdezni egy AI-tól, hogyan kezeljük az eszköz identitás konfliktusokat, nem csak dokumentációt, hanem a súlyokba és threshold-okba kódolt valódi érvelést is visszaadhatja.

A valódi tudás az edge case-ekben él. A fő folyamatok általában jól dokumentáltak. Az évi év során megoldott kivételek, special esetek, corner case-ek tartalmazzák a mély intézményi tudást.

A figyelmeztető jel

Van egy kellemetlen következménye mindennek: ha az üzleti logikád csak a kódodban van, és a kódod rossz test coverage-ű, homályos elnevezésű, vagy kaotikus struktúrájú, akkor egy halom tudáson ülsz, amit szinte lehetetlen kinyerni.

A ServiceMatch csapat azt találta, hogy az állításuk — miszerint "a repository elegendő" — kiszámítható módon csődöt mond. Naur tacit residue-ja valós. Néhány tudás tényleg csak az emberek fejében él.

De az erősebb megállapítás az, hogy több marad meg a kódban, mint gondoltuk. A repository sokkal több elméletet ragad meg, mint a dokumentáció valaha is tudna — csak egy új típusú olvasóra volt szükség, hogy kinyerjük.

Mit tegyél ezzel

Ha startup vagy növekvő tech cég vagy, itt egy keretrendszer a gondolkodáshoz:

1. Bízz a kódodban jobban, mint a docs-odban — amikor a kettő nem egyezik
2. Olyan kódot írj, ami dokumentálja az érvelését — értelmes változónevek, tiszta függvények, kommentek, amik a MIÉRT-et magyarázzák, nem csak a MIT
3. Kezeld a konfigurációt intézményi tudásként — azok a súlyok és threshold-ok döntések, amik megérnek egy megőrzést
4. Kezdj el AI eszközöket felfedezni — amik a kódbázist tudásforrásként tudják interrogálni

A kód, amit ma írsz, a holnap intézményi tudása. Érdemes jól megírni.