Блог


Маша и медведь. (К вопросу о читабельности кода)

Тут на днях объяснял человеку, как писать читабельный код. Ну что касается стиля, это я уже описывал здесь и здесь. Вопрос стоял в другом - что именно нужно отделять пустой строкой. С одной стороны лишние пустые строки вредят читабельности, ибо на экран входит меньше полезного кода. С другой стороны, без выделений получается каша. Где золотая середина?

Так вот, мне просто понравился пример, который случайно попался под руку. Сказка про Машу и медведя. Поделюсь с вами.



Вообще принцип написания читабельного кода прост. Любой код на скриптовом языке программирования, это обычный текст. Со смыслом. Ибо скрипт. это ни что иное, как сценарий, а сценарий должен писаться человекопонятным языком. Другими словами текст программы должен подчиняться законам лингвистики.

Для тех, кто плохо учился в школе, давайте разберем детский пример. Сказка (не вся, только начало, но и того хватит)

    Жили-были дедушка да бабушка. Была у них внучка Машенька.

    Собрались раз подружки в лес по грибы да по ягоды. Пришли звать с собой и Машеньку.

   — Дедушка, бабушка, — говорит Машенька, — отпустите меня в лес с подружками!

    Дедушка с бабушкой отвечают:


    — Иди, только смотри от подружек не отставай, не то заблудишься.


Тут мы видим, что для читабельности текст разделен на абзацы. В интернете стало принято выделять абзацы не только табуляцией, но и пустыми строками, оно нам и наруку.

Теперь представим этот фрагмент в виде функции или метода. Нам важен именно процедурный код, сами функции или методы и так понятно, что нужно выделять. Итак, приступим. В начале нам нужно определить персонажей, которые будут принимать участие в действе. Это дедушка, бабушка и их внучка Машенька.

В сказке это первый абзац, в программе - первый блок:

1
2
3
4
5
6
7

    
function fairyTale()
    {
        
$grandfather true;
        
$grandmother true;
        
$maria       createGrandkid($grandfather$grandmother);

Вот тут псевдоблок инициализации нужно отделить пустой строкой - абзацем.

Продолжаем. Дальше происходит какое то действие, в котором задействованы сторонние временные персонажи из других частей программы - подружки. Они взяли в свою компанию (массив) Машеньку и позвали в лес. Это уже другой псевдоблок, тут уже действия. Опять абзац:

1
2
3
4
5
6
7
8
9
10

    
function fairyTale()
    {
        
$grandfather true;
        
$grandmother true;
        
$maria       createGrandkid($grandfather$grandmother);
        
        
$girlfriends prepareForTravel('Forest');
        
array_push($girlfriends$maria);


Дальше в тексте прямая речь. И запрос условий. Тут сам Бог велел сделать пробел. Внутри этого блока дополнительное условие и вобщем то возврат промежуточного результата. Второе условие тоже нужно выделить:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    
function fairyTale()
    {
        
$grandfather true;
        
$grandmother true;
        
$maria       createGrandkid($grandfather$grandmother);
        
        
$girlfriends  prepareForTravel('Forest');
        
array_push($girlfriends$maria);
        
        if(
$grandfather  === true && $grandmother === true)
        {
            if(
in_array($girlfriends$maria))
                return 
goToForest($girlfriends);
            else
                return 
false:
        }
    }


Ну и так далее. Как будто пишем текст. В чем тут еще фишка. Есть место для комментирования псевдоблоков. В процессе разработки бывает полезно. Можно добавить, можно убрать, код не страдает:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    
function fairyTale()
    {
// Инициализируем переменные
        
$grandfather true;
        
$grandmother true;
        
$maria       createGrandkid($grandfather$grandmother);
    
// Подготовка к походу в лес. Добавляем Машу к компании подруг    
        
$girlfriends  prepareForTravel('Forest');
        
array_push($girlfriends$maria);
    
// Спросим, разрешат ли дед и бабка     
        
if($grandfather  === true && $grandmother === true)
        {   
// Если только не отстаенет от подруг
            
if(in_array($girlfriends$maria))
                return 
goToForest($girlfriends);
            else 
// Иначе нет. Дед строгий, но суровый.
                
return false:
        }
    }


Вообще, это очень хороший тренинг, представлять текст (особенно сказки) в виде программы. Помогает развивать не только "калиграфию", но и логику, умение выстраивать алгоритмы. Рекомендую.

 

Теги: PHP | Флейм

Комментарии (4)

I am
07-11-2014
Привидение кода в порядок - есть часть програмирования, это вроде как отделки в строительных работах, стена построена (код написан) и функция стены уже работает, тоесть закрывает, защищает и т.п., но если ее непривести в порядок (заштукатурить, покрасить, поклеить обои) то, не очень то хорошо получится.
volter9
13-12-2014
По моему, вот этот листинг:

$girlfriends  = prepareForTravel('Forest');
array_push($grandchild, $maria);

Должен быть:

$girlfriends  = prepareForTravel('Forest');
array_push($girlfriends, $maria);

К тому же, girlfriend это скорее девушка у парня а не подруга
Можно просто $friends.
Korset
21-01-2015
Хоть пока и не очень сведущ в этих делах, но соглашусь с предыдущим комментатором, более логично добавить Машу $maria в массив $girlfriends
twin
21-01-2015
И действительно... Откуда оно там взялось
Сейчас исправлю.

 
Наверх