Подписывайся на Telegram-канал

Самодокументируемый код

Самодокументируемый код

https://t.me/it_programmist

Все советуют писать комментарии в коде. Во-первых, вдруг кому-то придётся разбираться с твоим творением, во-вторых, через некоторое время комментарии тебе самому помогут понять, что ты такое тут написал.

У комментариев есть свои недостатки. Точнее недостатков у комментариев нет, они есть у тех, кто эти комментарии пишет.

Ты можешь начать играть в капитана-очивидность

Этим грешат очень многие, особенно, начинающие разработчики. Ну вот научили нас комментить всё на свете и получается потом

//сложение a и b
a+b

Код изменился - коммент старый

Бывает впопыхах поменял код, а коммент-то там остался прежний

//сложение a и b
a-b

И в следующий раз придётся потратить время, чтобы понять, что здесь что-то не так.

Комментарий непонятен

Бывает, что хотел реализовать один функционал и начал с коммента, а потом сделал вообще по-другому. Ну или просто у автора проблемы с выражением собственных мыслей.

/*Лунною тропою на свиданье еду
Тихо сам с собою тихо сам с собою
Я веду беседу*/
a+b

Комментарии, безусловно, нужны чтобы беглым взглядом понять что делают определённые участки кода или как использовать классы, элементы, шаблоны. Но есть интересные методики документирования.


Самодокументируемый код

Необходимость комментировать каждый свой чих отпадает, если придерживаться некоторых правил при написании кода.

Осмысленные имена

Всё просто:

- что переменная означает - так она и называется

- что функция делает - так она и называется.

Ничего не имею против девочек-программисток, но была коллега(недолго проработала), которая именовала переменные $a, $b, $c и т.д.
Когда доходила до $z, продолжала так: $aa, $ab, $ac.
t.me/progerdiary/49

Например, сразу понятно, что делает функция sendFile() и не до конца ясно, что конкретно делает функция manageFile().

Если функция что-то возвращает, то можно отразить это в имени readFile()

Сокращённые названия переменных непонятны: $a, $b, $z подойдут разве, что для счётчиков в циклах, хотя и те можно осмысленно обозвать.

Мой бывший коллега очень любил сокращать названия переменных и функций.Вот с первого взгляда не поймёшь, что такое oPub. One Publication!

Это, вероятно, самый мощный инструмент для самодокументирования. Ведь правильно подобранные имена делают многие комментарии просто ненужными.

Говорят, что труднее всего придумывать имена переменным. Но если ты не знаешь как назвать переменную в данном участке кода, скорее всего, ты не до конца понимаешь, что делает этот код.

Единая система именования

Не нужно каждый раз по-разному называть одно и то же:

$photo = getPicture();
....
$image = getPicture();
....
$picture = getPicture();

Константы вместо "магическиx чисел"

Бывает, что формулу программируешь, или просто так получилось, но есть "магическое число", которое просто есть.

Вместо

$circumference =2*3.14*r

лучше сделать

$pi = 3.14
$circumference =2*pi*r


Параметры функций

Тут, может, спорное утверждение и не всегда подходящее, но я стараюсь параметры функции передавать объектом или ассоциативным массивом

Вместо

let area = getTriangleArea(20,30);

Получается гораздо читабельнее:

let area = getTriangleArea({height:20,base:30});


Сюда же можно отнести следующий случай:

$array = json_decode($json, true);

Стандартная функция php. Понятно, что хотим распарсить JSON. Что за true не понятно.

С точки зрения самодокуентируемости, лучше было бы сделать отдельную функцию

$array = json_decode_to_associative_array($json);


Замена выражений или части кода на функцию.

Очень тяжело сразу понять несколько условий в операторе if():

if(!element.height && !element.width){
...
}

Можно заменить на функцию и назвать её таким образом, чтобы было ясно для чего нужна эта проверка

finction isVisible(){
return element.height && element.width
}
...
if(!isVisible){
...
}

Или

$size = $fileSize*1024;

лучше заменить на

$size = bitesToKBites($fileSize);
function bitesToKBites($fileSize){
return $fileSize*1024;
}

Замена на переменную

Иногда ситуации из предыдущего примера очень специфичны и используются только здесь и сейчас или ещё где-то здесь же рядом. Функцию можно заменить на переменную(константу)

const isVisible = element.height && element.width;


Интерфейсы классов и модулей

Есть у нас класс "коробка" и его состояние(state)

class Box {
setState(state) {
this.state = state;
}
getState() {
return this.state;
}
}

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

Гораздо понятнее будет, если, используя тот же state, переписать методы

class Box {
open() {
this.state = 'open';
}

close() {
this.state = 'closed';
}

isOpen() {
return this.state === 'open';
}
}

Всё ясно с первого взгляда.


Простой код с хорошим форматированием

Стремись к тому, чтобы ход «нормального» выполнения кода был очевиден. Обработка ошибок не должна отвлекать от нормальной последовательности выполнения. Условные конструкции  должны иметь единообразный порядок ветвей (например, всегда помещай ветвь «обычного» хода перед ветвью «обработки ошибок», или наоборот).

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


 Отдельные самостоятельные функции

Одна функция, одно действие. Повторяй как заклинание. Не пиши сложных функций, умеющих варить кофе, чистить ботинки и угадывать задуманное число. В одной функции должно выполняться одно действие! Выбери имя, недвусмысленно описывающее это действие. Если имя выбрано правильно, не нужно ничего больше комментировать!


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


_

И самое главное все это лишь рекомендации. Не следует слепо следовать этим правилам, жертвуя здравым смыслом! Если применение какой-либо вышеописанной методики кажется неуместной, то и не стоит её применять.


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

Но это не панацея. Документация и комментарии важны и нужны. Если использовать все методики документирования комплексно, то через какое-то время человек, разбирающийся в твоём коде, скажет тебе спасибо. А, вероятно, это будешь сам ты!!!

___

Я - программист!

Шутеечки в Дневнике программиста

Чат Клуб программистов

Ещё