Tiszta kódolás

„A kód mindig rohad” - Gémes Tamás
„Code are simple and direct like a prose” - Grady Booch

Általános alapvetések

Miért szükséges a tiszta kód? - kérdezhetjük. Egyszerű megközelítés: a fejlesztés idő, az idő pénz… De hol térül meg a befektetett idő, energia. A tiszta kód tanulható, csak eleinte jelent nehézséget és idővel rutinná válik. Ha ’smell’ kódot írunk, gyorsan lehet haladni, értjük is a saját magunk által megálmodott logikát, azonban, ha újra elővesszük a kódot, vagy másnak kell hozzányúlni (Code Legacy – Kód örökség), akkor fontos, hogy a pontos működést gyorsan megértsük és hozzá tudjunk fejleszteni. Grady Booch szerint úgy kell tudni olvasni, mint egy regényt. Nem szabad visszalapozni, egyértelműen sorról-sorra lehet értelmezni. Így a megértés és a hozzáírás fog lényegesen lerövidülni.

Duplikáció elkerülése

Ha már kétszer használunk kódot (számolást, visszatérést, megjelenést), saját függvényt, metódust írjunk. (Let DRY – Don’t Repeat Yourself). Egy megoldás csak egyszer implementáljunk. Ha redundánsan van jelen a kódban – let légyen az számítás, megjelenés, meghívás, stb., ha módosítani kell kényelmetlen és több hibázásra ad lehetőséget.

OCP

Open/Closed Principle – Legyen zárt a változtatásokra, de legyen nyitott a bővítésre. Egy új ’feature’ bevezetéséhez ne kelljen belenyúlni a régi kódba. Azonban a régi kódhoz tudnia kell kapcsolódni.

Code review

Csak abban az esetben, ha funkcionálisan megfelelően működik. Heti rendszerességgel a megírt kódokat közösen átvizsgáljuk. Így ki lehet szűrni a túlbonyolításokat, a code-smelleket, nem utolsó sorban tanulhatunk belőle, egymástól.

End-To-End felelősség

A kódért csoport felelősség van. Felel a tervező, a „designer”, a tesztelő, a kódoló és a manager is. Tervezéstől az üzemeltetésig. Ha ügyfél oldalról vizsgáljuk a felelősségi kérdést még inkább igaz ez – a cég a felelős. Ezért fontos, hogy a kódot mindenki magáénak érezze. Ha valaki ’out of project’ is ismerje, tegye bele a saját tudását. – visszacsatolva a Code review-ra

Kommentek

Kerüljük, ha csak lehet az öncélú kommentet („//” kerülése)… A saját, undeployed feladatoknál elfogadott. De távolítsuk el. Használjunk beszédesebb metódust, változó elnevezéseket. Később saját magunk sem emlékezünk rá mit is akartunk. Helyette saját (új) metódus bevezetése a célszerű.

// Check to see if the employee is eligible
// If full benefits
if(($employee->flags && $emloyee->age > 65) && $employee->dayOk)

helyett:

if ($employe->isEligibleForFullBenefits())

Hatékony is, mert elég a metódust updatelni és máris up-to-date a kódom. Azonban dolgozhatok duplán a kommentekkel, vagy rosszabb nem követem. A legnagyobb baj, ha „out-of-sync”-be kerülnek. Ezért code smell a comment is.

Elnevezések

Kerüljük a ’mental-mapping’-et.

$d = 7; //working day in the part of plant

helyett:

$plantWorkingDay = 7;

A mental-mapping egy belső térkép, szótár, amiből mi magunk tudjuk, hogy az adott változó (elnevezés) mögött milyen tartalom, funkció, eredmény van. Jobb esetben ezt kommenteljük, de a kód olvasásához nekünk is memorizálni kell - feleslegesen.

Elnevezés angolul (nyelvtani helyességgel), törekedve minél beszédesebb elnevezésre, csak az általánosan elfogadott rövidítések használatával (average = avg). De gondoljunk a szóbeli kommunikációra is, kiejthetőség elve és minél kevesebb legyen. Rossz példa:

getPmtCryByPmtId() : array

Meghatározó a neve a célja, a funkciója alapján, a benne lévő tartalom. Boolean típusnál nevezzük létigével ($isBeutifullCode, $hasBrownHair). Legyen főnév, get/set, „transaction”, „saveUserName”! Meghatározó a neve a célja, funkciója. A metódus minden esetben akció, lehet boolean típus is, ekkor létige/válasz pl. isMoreMoney() : boolean -- [true/false]. payment() vs. executePayment(). Mennyisége, egy vagy több. $user (ebben csak egy van? Ha igen helyes), $users, $userList

Metódusok (és osztályok)

Funkciók

Egy metódus (vagy függvény) egy funkció. Egyet csináljon (de azt jól). A hívó fél absztrakciós szintjén vizsgálva kell a metódust, vagy függvényt megírni. Egy egyértelmű feladat és részfeladatai. (Pure function).

Argumentumok

Maximum 3, de minél kevesebb annál jobb. Ha több, szervezd ki. Rossz példa:

public function drawCircle($x, $y, int $radius, int $red, int $green, int $blue)
{
draw [$x, $y, $radius, [$red, $gree, $blue]];
}

Helyesen:

public function DrawCircleFromObject(CenterPoint $centerPoint, CircleParams $circleParams)
{
  draw [$centerPoint->points(), $circleParams->radius(), $cirlceParams->colors()];
}
class CenterPoint
{
  public function points()
  {
    return [1,2];
  }
}
class CircleParams
{
  public function colors()
  {
    return [20, 96,130]
  }
  public function colors()
  {
    return [5]
  }
}

vagy:

<?php
class MenuConfig
{
   public $title;
   public $body;
   public $buttonText;
   public $cancellable = false;
}

$config = new MenuConfig();
$config->title = 'Foo';
$config->body = 'Bar';
$config->buttonText = 'Baz';
$config->cancellable = true;

function createMenu(MenuConfig $config) {
  // ...
}

Elképzelhető több munka ma, de a jövőben, ha valaki olvassa a kódot sokkal egyszerűbb lesz megérteni a működést.

Kerülni kell a flag típusú argumentumot (true/fals). Mert itt már két értékkel tér vissza, vagy ’A’-t csinál vagy ’B’-t. Máris két funkciója van.

Mellékhatások kerülése. Vagyis, ha egy metódus a hatókörén kívül „kontárkodik”.

class User {
   public function checkPassword (string $username, string $password)
   {
      if ($this->encriptPassword($password) === $password) {
        setCookie (’userLoggedIn’, true);
        return true;
      }
   }
}