Špatně čitelný dokonalý kód

Školení, která pořádám

U českého překladu knihy Dokonalý kód místy dost trpím. Čas od času si musím dělat zpětný překlad do angličtiny, abych pochopil, co měl původní autor nejspíš na mysli. Hlavně se ale v ukázkách kódu míchají české identifikátory s anglickými – např. NextEmployee($zaměstnanec) je toho běžná ukázka, ale často se vyskytují i horší obraty – např. pět proměnných na stejné úrovni, z nich tři pojmenované česky a dvě anglicky. Jde o velmi častou chybu, tím spíš ale nechápu, že ji překladatel, korektor i editor v knize připustil. Já jsem si na to ve své knize dal pozor, v knize pojednávající o kvalitním kódu to je ale ještě důležitější.

Pozitivní nebo negativní podmínka?

Občas ale nesouhlasím ani s autorovými názory na to, jak má čitelný kód vypadat. Např. toto je ukázka kódu, který by údajně měl být dobře čitelný:

<?php
OpenFile($inputFile, $status);
if ($status == STATUS_SUCCESS) {
    RetrieveFile($inputFile, $fileData, $status);
    if ($status == STATUS_SUCCESS) {
        SummarizeFileData($fileData, $summaryData, $status);
        if ($status == STATUS_SUCCESS) {
            PrintSummary($summaryData);
            SaveSummary($summaryData, $status);
            if ($status == STATUS_SUCCESS) {
                UpdateAllAccounts();
                EraseUndoFile();
                $errorType = ERROR_TYPE_NONE;
            } else {
                $errorType = ERROR_TYPE_SUMMARY_SAVE_ERROR;
            }
        } else {
            $errorType = ERROR_TYPE_DATA_SUMMARY_ERROR;
        }
    } else {
        $errorType = ERROR_TYPE_FILE_READ_ERROR;
    }
} else {
    $errorType = ERROR_TYPE_FILE_OPEN_ERROR;
}
?>

Podle mě je tento kód čitelný velmi špatně. Kniha by měla upozornit na to, že mnohem lepší čitelnosti bychom v tomto případě dosáhli ošetřením chyb pomocí výjimek:

<?php
try {
    OpenFile($inputFile);
    RetrieveFile($inputFile, $fileData);
    SummarizeFileData($fileData, $summaryData);
    PrintSummary($summaryData);
    SaveSummary($summaryData);
    UpdateAllAccounts();
    EraseUndoFile();
    $errorType = ERROR_TYPE_NONE;
} catch (FileException $e) {
    $errorType = $e->getType();
}
?>

I když se ale budu soustředit na hlavní myšlenku, kterou se kniha původní ukázkou snažila předat (za if vždy uvádět pozitivní případ), tak s ní nesouhlasím. Spíše se totiž kloním k tomu za if uvádět kratší blok, což způsobí, že se na konci kódu (a velmi daleko za původní podmínkou) nehromadí řada klauzulí else, u kterých není na první pohled patrné, k jaké podmínce se vztahují.

Seznamy volání

Další ukázka „zčitelnění“ kódu na mě působí ještě hůř. Nejprve jak vypadal původní kód:

<?php
if ($inputCharacter < ' ') {
    $characterType = CHARACTER_TYPE_CONTROL_CHARACTER;
} elseif ($inputCharacter == ' '
    || $inputCharacter == ','
    || $inputCharacter == '.'
    || $inputCharacter == '!'
    || $inputCharacter == '('
    || $inputCharacter == ')'
    || $inputCharacter == ':'
    || $inputCharacter == ';'
    || $inputCharacter == '?'
    || $inputCharacter == '-'
) {
    $characterType = CHARACTER_TYPE_PUNCTUATION;
} elseif ('0' <= $inputCharacter && $inputCharacter <= '9') {
    $characterType = CHARACTER_TYPE_DIGIT;
} elseif (('a' <= $inputCharacter && $inputCharacter <= 'z') || ('A' <= $inputCharacter && $inputCharacter <= 'Z')) {
    $characterType = CHARACTER_TYPE_LETTER;
}
?>

A teď co s ním autor provedl, aby ho vylepšil:

<?php
function IsLetter($inputCharacter) {
    return ('a' <= $inputCharacter && $inputCharacter <= 'z') || ('A' <= $inputCharacter && $inputCharacter <= 'Z');
}

function IsPunctuation($inputCharacter) {
    return $inputCharacter == ' '
        || $inputCharacter == ','
        || $inputCharacter == '.'
        || $inputCharacter == '!'
        || $inputCharacter == '('
        || $inputCharacter == ')'
        || $inputCharacter == ':'
        || $inputCharacter == ';'
        || $inputCharacter == '?'
        || $inputCharacter == '-'
    ;
}

function IsDigit($inputCharacter) {
    return '0' <= $inputCharacter && $inputCharacter <= '9';
}

function IsControl($inputCharacter) {
    return $inputCharacter < ' ';
}

if (IsLetter($inputCharacter)) {
    $characterType = CHARACTER_TYPE_LETTER;
} elseif (IsPunctuation($inputCharacter)) {
    $characterType = CHARACTER_TYPE_PUNCTUATION;
} elseif (IsDigit($inputCharacter)) {
    $characterType = CHARACTER_TYPE_DIGIT;
} elseif (IsControl($inputCharacter)) {
    $characterType = CHARACTER_TYPE_CONTROL_CHARACTER;
}
?>

Na řídícím kódu mi nejvíc vadí ručně vyrobený seznam volání. Představte si, jak by kód vypadal, když bychom časem přidali dalších 10 druhů znaků. Vznikl by ještě delší seznam bez jakékoliv myšlenky a s nízkou informační hodnotou, který bychom museli ručně rozšiřovat. Vadí mi i určitá nekonzistence – proč se funkce jmenuje IsControl a konstanta CHARACTER_TYPE_CONTROL_CHARACTER?

Jak bych úlohu vyřešil já?

<?php
$characterTypes = array( // type => regexp character class
    CHARACTER_TYPE_LETTER => 'a-zA-Z',
    CHARACTER_TYPE_PUNCTUATION => ' ,.!():;?-',
    CHARACTER_TYPE_DIGIT => '0-9',
    CHARACTER_TYPE_CONTROL_CHARACTER => '\0-\x1F',
);
foreach ($characterTypes as $type => $regexp) {
    if (preg_match("(^[$regexp]\$)", $inputCharacter)) {
        $characterType = $type;
        break;
    }
}
?>

Řídící kód je trošku složitější, ale definice jednotlivých znaků je přehledná, snadno upravitelná a triviálně rozšiřitelná. Takže když bychom chtěli přidat další typ znaků, můžeme to udělat na jednom místě s minimální ruční prací.

Jakub Vrána, Dobře míněné rady, 15.7.2011, diskuse: 52 (nové: 0)

Diskuse

Tomas Volf:

Tahle kniha nezni dobre, ale zkuste tuhle... je snadno k sehnani pres torrenty pokud ji chcete jenom prolistovat... http://www.amazon.com/Clean-Code-Handbook-…/0132350882

15.7.2011 03:19:18

Tharos:

Odkazované knize dávám palec nahoru, dala mi toho dost. Ale knihu Dokonalý kód jsem nečetl, takže nemohu srovnat. Třeba by ani na odkazované nenechal Jakub nit suchou :).

15.7.2011 11:01:28

root:

Autor knihy nepredpoklada, ze se pouzije jako programovaci jazyk php - oni totiz existuji i jazyky bez exceptions a bez regexpu ve standardni knihovne - proto by upraveny priklad s exceptions nesel napr. v jazyku C.

V druhem prikladu si myslim, ze slo hlavne o zabaleni nic nerikajicich podminek do logickych funkci, takze pri cteni slozite podminky je hned jasne o co jde.

Pokud se omezime na php tak nove navrzeny priklad s exceptions je prehlednejsi.

Pro programatora, ktery neovlada regexp je prehlednejsi serie ifu nez regexp.

15.7.2011 09:11:06

Jakub Vrána :

Série ifů je to, co mi v posledním příkladě vadí především. Kód bez jakékoliv myšlenky vzniklý metodou copy–paste.

15.7.2011 10:31:27

Richard:

Root mi mluví z duše. To že první příklad není typický pro PHP je pro C je očividné. Druhý příklad je opět typicky z C. JV řešení bohužel toto vůbec nebere v potaz a také i v případě PHP je úplně pomíjen výsledný výkon takového "čitelného kódu".

15.7.2011 11:46:20

Jakub Vrána :

Na jazyku nezáleží. Na prvním příkladu mi vadí čtyři různě odsazené bloky else pod sebou, u kterých není na první pohled patrné, k čemu se vztahují. U druhého příkladu mi vadí ručně vytvořený seznam volání. Těchto obratů se chci zbavit těmi prostředky, které jazyk nabízí. V PHP to jde způsobem, který jsem popsal, v C by to šlo taky (i když trochu jinak).

15.7.2011 12:00:42

NoxArt:

Tady s Jakubem se vším souhlasím

Kód takový že pro odsazení už je i začátek řádku málem mimo obrazovku opravdu není nic čitelného. Píšete že to v C nejde a přitom první příklad v něm jde úplně triviálně, stačí se nedržet dogmaticky pozitivnosti podmínky; druhý by šel taky

Tvá zmínka o výkonu je jen plácnutím - udělal jsem test 2. kódu a Jakubův je asi 50x rychlejší...

1. kód taky nemá důvod být pomalejší

Špatně čitelný dokonalý kód

Školení, která pořádám

Pozitivní nebo negativní podmínka?

Seznamy volání

Diskuse

Tomas Volf:

Tharos:

root:

Jakub Vrána :

Richard:

Jakub Vrána :

NoxArt:

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

Michal:

Opravdový odborník :-):

Michal:

Jakub Vrána :

Opravdový odborník :-):

Michal:

Michal:

Tomáš Fejfar:

Jakub Vrána :

Opravdový odborník :-):

David Grudl:

Michal:

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

Filip Procházka:

David Grudl:

maryo:

Opravdový odborník :-):

Michal:

Jakub Vrána :

Opravdový odborník :-):

Jakub Vrána :

Opravdový odborník :-):

NoxArt:

Jakub Vrána :

Opravdový odborník :-):

Lukyer:

Michal:

Opravdový odborník :-):

Michal:

Opravdový odborník :-):

Lukyer:

Jakub Vrána :

Navigace

PHP triky

Kupte si mou knihu

Reklama

Web běží na serveru

Články podle skupin

Výběr článků

Nejnovější články

Normy a manuály

Další projekty