Már sokszor utaltam arra, hogy mennyire fontos az, hogy a fejlesztett szoftverünk kódja jól olvasható legyen. Egy jól olvasható kód magáért beszél: csökkenti a fejlesztők közötti közvetlen kommunikáció szükségességét, valamint lehetővé teszi, hogy a szoftver könnyebben továbbfejleszthető, karbantartható legyen.
Ha jó a kód, akkor abból “visszafejthető” maga az üzleti igény, a mögöttes üzleti gondolkodás. A mai post-ban való világbeli példákat vettem elő.
Az éjjelnappali akciója
Nemrég egy éjjelnappali kisbolt akciójára lettem figyelmes:
 |
2l Coca cola, 2l Cola light, 2l Zéró-t Ha vesz ajándék po- harat adunk 2db esetén! |
|
Nem kicsit vicces a megfogalmazás, de amúgy egy kis gondolkozás után mindenki számára érthető: “2db 2L-es Coca Cola üdítő (Coca Cola, Coca Cola Light vagy Coca Cola Zero) megvásárlása esetén ajándék poharat adunk!”
A probléma gyökere a szavak sorrendjében keresendő. A mondat közben elejtett “ha vesz”, ill. a mondatvégi “2db esetén” a gondolat elejére kívánkozik, így érthető tisztán a gondolatmenet: ha X, akkor Y.
BKV-vonaljegy
Fogósabb a BKV-vonaljegy hátoldalára írt üzenet megfejtése (bocs, már érvényesítettem a jegyet, ezért egy része nem látszik a képen).
 |
| (i) Érvényes egy utazásra, átszállás és az utazás megszakítása nélkül, autóbuszon, villamoson, trolibuszon, fogaskerekűn a járatok teljes hosszán, HÉV-en a Budapest határán belüli vonalszakaszokon.
(ii) Az érvényesség időtartama alatt a metróhálózaton belül (ideértve a földalattit is) átszállásra jogosít. (iii) A jegyet a metrón és a földalattin az utazás megkezdése előtt, a többi közlekedési eszközön a felszállás után kell érvényesíteni. (iv) Bélyegzős érvényesítés esetén a kezeléstől számított 60 percig jogosít utazásra, az éjszakai járatokon 90 percig érvényes. (v) A jegyet ellenőrzéskor fel kell mutatni, és az ellenőrzést végző személy kérésére át kell adni. |
Mit is jelent ez? Az Index is foglalkozott ezzel az üggyel, az ő olvasatukban: “Január elsejétől a BKV azon járatain, ahol dátum kerül az érvényesített vonaljegyre, 60 percig lehet utazni az átszállások számától függetlenül. Ez igaz a metróra, a kisföldalattira és egyes felszíni járatokra is.”
Én először az Index videójából értesültem erről a változásról, ezért “elhittem”, amit ők gondoltak. Azóta a barátnőm érdeklődött egy jegypénztárnál, ahol az ott dolgozó munkatársnő egyértelműen letagadta, hogy ez igaz lenne. A kérdés elég konkrét volt: “ha metróval utazom, utána átszállhatok-e villamosra, miközben ugyanazt a vonaljegyet használom?”
Gondoltam, előveszem a vonaljegyet, és elkezdem megérteni mi is van rá írva.
- mondat jelentése: nem lehet megszakítani az utazást, ill. átszállni a jeggyel, ha nem metrón közlekedünk.
- mondat jelentése: a metróhálózaton belül lehet átszállni a jeggyel.
- mondat jelentése: ha bélyegzős érvényesítés történik, 60p-ig lehet utazni a jeggyel akár átszállással is (éjszakai járatokon 90p-ig).
- ill. (v) mondat jelentése ebben a kontextusban nem releváns.
Na, és mi is van akkor, ha először metrón utazom, és utána átszállok egy villamosra? A metróhálózaton átszállhatok, és 60p-ig érvényes a jegyem (nap közben), ha villamoson utazom, akkor viszont hiába kerül rá a bélyegző, nem szállhatok át másik járműre új vonaljegy érvényesítése nélkül. De akkor mi van, ha metróról szállok át villamosra?!!
Teljesen megtévesztő a szövegezés, nem egyértelmű, ráadásul ha csak egyes elemeit vizsgáljuk, teljesen más következtetésre is juthatunk (pl. az (iv) mondat esetén).
Mi van akkor, ha autóbuszon felkerül a bélyegző a vonaljegyre, és már több, mint 60p-e utazunk? Pl. a 7-es buszon a két végállomás között 43p a menetidő, ez egy jó kis fővárosi dugóban könnyen túlléphető. (Az (i) mondat azt mondja viszont, hogy a teljes vonalon utazhatunk.)
Ha csak a metrókra érvényes a 60p-es bélyegzős érvényesítés (mivelhogy a többi járműtípuson úgyis csak átszállás nélkül utazhatunk egy jeggyel), akkor miért írják oda, hogy az éjszakai járatokon 90p-ig érvényes a jegy? A metrónál nincs is éjszakai járat.
Amúgy az angol szöveg azt sejteti, hogy kizárólag a metrón belül lehet átszállni. Mi lett volna, ha ezt írja a BKV?:
“Érvényes a teljes metróhálózaton belül tetszőleges átszállással a jegy érvényesítésétől kezdve 60p-ig. A többi járattípuson (autóbusz, villamos, trolibusz, fogaskerekű) a járat teljes hosszán egy utazásra érvényes – átszállás és az utazás megszakítása nélkül.” (De még mindig nem értem az éjszakai járatokat.)
Szóval számomra ez teljes káosz. (Ha vki megtalálja a megfejtést, kérem, ossza meg!)
GUI-forráskód
Az alábbi leegyszerűsített Javascript függvényrészlet egy felhasználói felületen engedélyez control-okat. (Elrejti/megjeleníti őket, enabled-dé/disabled-dé teszi őket.) A spagetti kódból csak azokat a részket hagytam meg, amik az ún. “szolgalatiUtonFelterjesztendo” checkbox-szal állnak kapcsolatban.
Az eredeti kód ennél sokkal hosszabb, és kb. egy tucatnyi control állapotát állítja. Meg tudja-e mondani vki ezek után, hogy:
- mikor látható a “szolgalatiUtonFelterjesztendo” checkbox?
- mikor engedélyezett (enabled)?
Ehhez már nem kevés gondolkozás kell. Természetesen létezik megoldás, amellyel a kód sokkal áttekinthetőbbé tehető:
Ezek után már nem lehet senkinek sem kétsége afelől, hogy mikor kell megjelennie a checkbox-nak. Ráadásul ha vki ismeri az üzleti problémát is, akkor szinte teljes megvilágosodás érhető el a kód olvasásakor.
Konklúzió
Ugyan általános receptet nem lehet adni arra, hogy hogyan kommunikáljunk, fogalmazzunk, azonban van pár dolog, amire célszerű törekedni:
- Legyünk egyértelműek!
- Törekedjünk a lényegre! Mellőzzük az oda nem illő, felesleges részleteket, csapongásokat!
- Ne bonyolítsuk túl!
- Legyen egy folyamatos gondolatmenete annak, amiről írunk! Legyen eleje, és vége!
Én, amikor írok (akár forráskódról, akár doksiról, akár blog írásáról van szó), a leírt részeket újra és újra elolvasom az elejétől. Megpróbálok szűz szemmel olvasni, és próbálom átérezni, hogy hogyan is kapcsolódnak a gondolatok egymáshoz, hogyan építkeznek. Eközben mondatokat, bekezdéseket, programkódokat, gondolatokat török ketté, vonok össze. Az is lehet, hogy kidobok teljes bekezdéseket, mert felesleges szócséplésnek tartom őket. A lényeg, hogy miközben írok, saját gondolataimat rendszerezve egy sokkal világosabb, értékesebb írást készítsek el.
