Save dokumentuojantis kodas

Save dokumentuojantis kodas - tai tokia teoriškai gal ir ne visia bloga, bet praktiškai daugiau atsikalbinėjimams naudojama koncepcija apie tai, kad programa gali būti parašyta taip, kad ją skaitant, savaime galima būtų suprasti, kas tenai parašyta, o todėl nereiktų papildomos informacijos ar kokių tai programinių komentarų, kurių beveik visi programuotojai kažkodėl vis vengia ir vengia.

Pirma programavimo kalba, kuri buvo pateikiama kaip esą save dokumentuojanti, buvo COBOL, kurią paskui dešimtis metų keikė visi programuotojai iš eilės ir visi sakydavo, kad tai siaubas. Reikia pripažinti, kad kadangi ta kalba buvo nuo pat pradžių kuriama kaip kuo panašesnė į žmonių kalbą ir su pertekliniais verbalizavimais, tai matyt joje vienintelėje išties bent minimaliai ir veikė tas savęs dokumentavimas. Jokioje kitoje, vėliau sukurtoje programavimo kalboje to pasiekti daugiau nepavyko.

Nepaisant to, liko tiesiog gero programavimo principai:

• Kodo komentavimas - 25% arba daugiau viso programos teksto turi sudaryti komentarai, kurie būtų prasmingi ir naudingi
• Kintamųjų ir funkcijų įvardinimas prasmingais vardais - pvz., ne $x ir ne $y, kurie kartojasi ir nieko nereiškia, o $kaina ir $antkainis
• Kintamųjų ir funkcijų įvardinimas su kontekstiniais prefiksais - $sandėlio_kaina, $pardavimo_antkainis, kurie skiriasi nuo $tiekimo_kaina, $pardavimo_kaina ir $mokestinis_antkainis, $kliento_antkainis
• Kodo struktūra: pirma duomenų deklaravimas, pirminis jų teisingumo patikrinimas, klaidų taisymas ir apdirbimas, o paskui - reali kodo logika, t.y., veiksmai
• Tvarkingas kodo formatavimas, kuris atitiktų loginę kodo struktūrą
• Lengvas kodo skaitomumas svarbiau už gudrius programavimo fyntus

Nors šitų kelių taisyklių daugeliu atvejų visvien nepakanka, bet jos jau pagerina kodo lygį tiek, kad skaitant galima kažkiek suprasti, kas vyksta. Darant kodo refaktoringą, tikras tikslas ir būna sukurti tokį kodą, kuris atitiktų tuos aukščiau išvardintus principus.

Gero, lengvai skaitomo, t.y., save dokumentuojančio kodo praktika - vengti inline arba shorthand tipo konstrukcijų, ypač skirtų sąlyginiams perėjimams, o taip pat vengti kišti kelis veiksmus į vieną eilutę, nes tai spagečių kodo gaminimo įrankiai.

Kaip pvz., geras ir lengvai suvokiamas kodas:

$a = 5;
if ($a < 10) {
    $b = "Hello";
}
echo $b;
<pre>

Kaip pvz., analogiškas shorthand tipo kodas, kuris nevaldomas:
<pre>
$a = 13;
$b = $a < 10 ? "Hello" : "Good Bye";
echo $b;