Šis sąrašas padės jums parašyti aukštos kokybės programas

Raphael Finkel, 8/17/2005

Identifikatoriai: įsitikinkite, kad visi jūsų identifikatoriai turi prasmę.

1. Vienos raidės identifikatoriai dažniausiai neturi prasmės.

2. Pavadinimai, tokie kaip flag ir temp retai kada turi prasmę. Vietoje flag, pabandykite Būlio sąlygą, kurią ji tikrina, pavadinti pvz.,valueFound.

3. Apsvarstykite kelių žodžių identifikatorius, tokius kaip nameIndex. Ilgi identifikatoriai (bet ne per ilgi) paprastai yra gerai skaitomi.

Literalai: programoje venkite skaičių, išskyrus 0 ir 1 bei eilučių, išskyrus "", nebent apibrėžiate konstantas.

1. Nenaudokite sveikojo tipo literalo kaip array masyvo (angl. array bound).

2. Nenaudokite sveikojo tipo literalo kaip vykdymo parametro, pavyzdžiui, skirtojo laiko ar prievado numerio.

3. Nenaudokite sveikojo tipo literalų norėdami parinkti meniu elementus.

4. Nenaudokite sveikojo tipo literalo išmatuoti eilutės ar kai kurių duomenų dydžiui; C ir C++ naudokite sizeof() ir strlen(), o Java naudokite .length() ir.size.

5. Nenaudokite sveikojo tipo eilutės failo pavadinimui. Vis dėlto, sveikojo tipo eilutes galite išvesti.

6. Nenaudokite sveikojo tipo literalo norėdami indeksuoti masyvą, kuriame yra įvairiarūšiai duomenys (angl. heterogeneous data).

7. Nerašykite identifikatoriaus pavadinimu, reiškiančiu literalą, pvz., „trisdešimt“.

Moduliarizacija: programa sukurta iš sąveikaujančių komponentų.

1. Nerašykite viso kodo į main() programą (angl. routine).

2. Neapkraukite programų per dideliu darbo krūviu. Jei programa ilgesnė nei 50 eilučių, ji gali būti per ilga.

3. Jei kodą kartojate kelis kartus, pagalvokite, kas geriau veiktų – ar ciklas, ar paprogramė (angl. subroutine).

4. Jei pastebite, kad įtraukos pasidarė labai gilios, tikriausiai nenaudojate paprogramių tada, kada turėtumėte.

5. Iš naujo nekurkite programos bibliotekos (nebent to reikalauja užduotis). Vietoje to, peržvelkite vadovus ir išmokite apie sprintf() ir atoi().

6. Naudokite C ir C++ antraštės failus (antraštės failų pavadinimai baigiasi .h), kad apibrėžtumėte visas konstantas, kurių reikia keliems failams ir sužinotumėte visas paprogrames, eksportuojamas tarp failų. Tačiau nedėkite paprogramių turinio (angl. body) į antraštės failus (išskyrus retas pasitaikančias įterptas paprogrames (angl. inline subroutine).

Formatavimas: jūsų programa turi būti lengvai skaitoma.

1. Aiškių pasiūlymų dėl formatavimo ir kitų pateikimo problemų rasite adresu http://geosoft.no/development/javastyle.html. Ši nuoroda yra skirta „Java“, tačiau taip pat bus naudinga ir kitoms kalboms.

2. Pabandykite apriboti visas eilutes iki 80 simbolių; dėl istorinių priežasčių daugelis žmonių peržiūri kodą 80 stulpelių languose.

3. Įtraukai nenaudokite ir tabuliacijos klavišo ir tarpų, nes ne visos teksto rengyklės tabuliacijos klavišą traktuoja kaip 8 tarpus.

4. Laikykitės nuoseklaus įtraukos modelio, kuris atspindi programos valdymo struktūrą.

5. Venkite pasikartojančių tuščių eilučių savo programoje. Tarp paprogramių pakanka vienos tuščios eilutės.

6. Skirtingos operacinės sistemos eilutes užbaigia skirtingais būdais. Jei persikeliate tarp Win32 (kur naudojama \r\n), Unix (kur naudojama \n) ir MacOS (kur naudojama \r), iš naujo suformatuokite failą, kad galėtumėte naudoti nuoseklų eilutės užbaigimo būdą.

7. Nenustatykite vykdomojo bito (Unix) savo šaltinio failuose.

Kodavimas: jūsų kodavimas turi būti aiškus, lengvai prižiūrimas ir efektyvus, tokia seka. Kai kurios čia pateiktos taisyklės yra konkrečios, kitos – bendros.

1. Nenaudokite if teiginių sekos, kuri neturi else ir turi tik vieną atitikmenį; vietoje to, naudokite else if.

2. Kai norite suskirstyti teksto įvestį į kategorijas, nerašykite pirmųjų galimų simbolių.

3. Kurdami bitų šablonus, vietoje daugybos (angl. miltiplication) naudokite shift operatorių.

4. Visada patikrinkite ar switch teiginyje nėra numatyto teksto. Taip pat if-then-else teiginių sekoje naudokite galutinį else.

5. Visada patikrinkite grįžimo kodą ir naudokite perror(), kad praneštumėte apie trikdį.

6. Būlio vertės visada turėtų naudoti boolean tipą Java, bool C++ ir sveikuosius skaičius 0/1 C. Nenaudokite simbolių t ir f, taip pat nenaudokite -1 ir 1.

7. Jei įmanoma, naudokite ciklus duomenų struktūroms inicijuoti.

8. Kiekvieną kintamąjį ir kiekvieną struktūros lauką naudokite tik vienam tikslui. Neperkraukite jų, nebent tam yra rimta priežastis.

9. Nenaudokite to paties identifikatoriaus tipui, kintamajam ir failo pavadinimui, net jei pakeisite didžiąsias raides. Tai per daug painu.

10. Jei keičiate duomenis naudodami htonl() ar panašią programą, prieš tinklo perdavimą, nekeiskite duomenų. Sukurkite antrą duomenų struktūrą.

11. Stenkitės nenaudoti visuotinių ar nelokalinių (angl. global, nonlocal) kintamųjų. Kiekvieną kintamąjį rašykite mažiausioje apimtyje. Yra teisėtas nelokalinių kintamųjų panaudojimas, tačiau įsitikinkite, kad jums jų tikrai reikia.

12. Shell, Perl ir Python programos turi turėti savo #! eilutę kaip pirmąją failo eilutę, kitu atveju, tokia eilutė yra tik komentaras.

13. Stenkitės vengti koduoti specialius atvejus. Dažnai galite panaudoti pseudoduomenis ar kitus duomenų struktūros metodus, kurie leidžia specialius atvejus paversti į įprastus atvejus.

Kompiliatoriai: leiskite jiems padėti rasti klaidas. Visada iškvieskite kompiliatorius su įjungtais įspėjimais.

1. C ir C++, naudokite -Wall vėliavėlę.

2. Java, naudokite -Xlint:all -deprecation ir pmd programą, kad gautumėte geresnio stiliaus pasiūlymų.

3. Python, naudokite -t -W all.

4. Perl, naudokite -w vėliavėlę ir nurodykite use strict. Cgi-bin skriptai taip pat turėtų turėti -T vėliavėlę.

Gamybos įrankis: naudokite jį, naudokite jį gerai.

1. Gamybos failas visada turi turėti „švarų“ receptą, kuris turėtų pašalinti visus failus, kuriuos galima atkurti pasinaudojus kitais gamybos faile esančiais receptais, įskaitant objektų ir vykdomuosius failus.

2. Jei jūsų projekte yra keli šaltinio failai, jei reikia, gamybos failas turėtų sugeneruoti objekto (.o) failus ir juos susieti.

3. Gamybos failas turi būti parašytas taip, kad jei jį paleisite du kartus iš eilės, antrasis paleidimas dar kartą nekompiliuos.

4. Kiekvienas receptas turi sukurti failą, nurodytą jo taikinyje.

5. Kiekvienas receptas turi naudoti kiekvieną failą, nurodytą jo būtinų sąlygų sąraše.

6. Išmokite naudoti taisykles tokiems tikslams kaip .c.o, kad išvengtumėte pasikartojančių gamybos failų.

7. Jei turite tik vieną C arba C++ šaltinio failą, vykdomasis failas turi turėti tą patį pavadinimą (be plėtinio .c arba.cpp).

8. Būtinai nurodykite visus .h failus kaip būtinas sąlygas ten, kur jų reikia. Apsvarstykite galimybę naudoti makedepend, būtinųjų sąlygų sąrašo sukūrimui.

Dokumentacija: skirta ne tik pažymius rašančiajam. Tai taip pat padės jums rašant programą!

1. Rašydami programą nepamirškite dokumentacijos. Keičiantis dizainui visada galėsite ją modifikuoti.

2. Parašykite išorinę dokumentaciją: kaip sukompiliuoti ir paleisti programą ir ką ji turi daryti? Išorinė dokumentacija paprastai yra atskirame README faile; mažuose projektuose ji gali būti komentaras šaltinio faile.

3. Įtraukite vidinę dokumentaciją: kokius algoritmus ir duomenų struktūras naudojate? Apžvalga gali būti atskirame README faile, tačiau paprastai vidinė dokumentacija pateikiama apie konkrečias procedūras, deklaracijas ir veiksmus, kuriuos ji apibūdina.

4. Patikrinkite visą programą ir dokumentaciją, ar nėra rašybos klaidų. Nemandagu pateikti darbą su rašybos klaidomis ir tai demonstruoja nedėmesingumą detalėms.

5. Patikrinkite visus savo dokumentus (ir išvesties pranešimus), ar nėra gramatikos klaidų.

6. Programos yra daug lengviau skaitomos, jei pateikiate trumpą komentarą skliaustuose. Pvz., skliaustas, uždarantis sąlygą gali turėti tokį komentarą kaip „jei vertė gerai“. Ciklą užbaigiantis skliaustas gali turėti komentarą, pvz., „kiekvienai įvesties eilutei“. Skliaustas, uždarantis procedūrą, gali turėti komentarą, tik įvardijantį procedūrą. Klasę užbaigiantis skliaustas gali turėti komentarą „klasė“ ir klasės pavadinimą.

Original article: https://www.cs.uky.edu/~raphael/checklist.html