5 съвета за по-чист код

„Не е достатъчно кодът да работи.“
― Робърт К. Мартин

Кодът трябва да е чист, четим и оптимизиран. Изпитвали ли сте някога усещането да се опитвате да прочетете код с разхвърлян синтаксис, разбити заедно огромни блокове от кодове или просто някои произволно изпуснати функции? Да, всички бяхме там. Когато екип работи едновременно върху код, това вероятно е ежедневен проблем. Има някои хакове, които буквално ще улеснят живота ви, като се научите как да пишете чист код.

В тази публикация ще споделя някои добри практики, които научих в кариерата си на софтуерно инженерство, които могат да ви направят кода „по-чист“.

Какво е чист код?

Първо нека започнем с това какво е чист код. Когато чуете чист код, кое е първото нещо, което ви идва наум? Със сигурност няма едно определение какво прави кода по-чист. Всеки има нещо в главата си, така че попитах няколко души какво е тяхното определение. Ето същността на това, което получих:

Лесен за разбиране и промяна — кодът е написан по такъв начин, че се опитва да не обърка читателя и няма скрити грешки;
Прост и директен — като предишния, казано с различни думи;
Написан внимателно — някои казват, че писането на код е занаят. И както всеки друг занаят, грижата за него дава по-добри резултати;
Ефективен — използва подходящи алгоритми по оптимален начин;
Тестван — има достатъчно тестово покритие. Прави го по-безопасен за промяна и по-лесен за разсъждение относно неговото намерение;
Избягва дублирането — Няма какво повече да се каже, че дублираният код е лош код и може да доведе до много проблеми.

В тази публикация ще се съсредоточа върху първите две, писане на код, който е лесен за разбиране и промяна. Въпреки че пишем кода си, за да работи на компютри, той ще бъде прочетен и от хората. Компютрите разбират целия код, ако той се компилира. Но за хората трябва да положим малко повече усилия. Писането на прост и директен код ще помогне на другите, които го четат, и ще ви помогне, когато трябва да промените нещо след една година. И като бонус много вероятно ще започнете да получавате по-благоприятни отзиви за кода 😉

Наименуване на нещата

Наименуването е основна част от писането на код. Трябва да измислите много имена. Имена на променливи, функции, аргументи на функции, класове, директории и още и още. Понякога има дефинирани правила, които помагат, например при наименуване на микроуслуга или хранилище за вашата компания, но често няма и сме оставени на собственото си въображение. Което понякога ни проваля. Има само две трудни неща в компютърните науки: обезсилване на кеша и наименуване на неща.

Фил Карлтън
https://www.karlton.org/2017/12/naming-things-hard/

И така, можем ли да улесним нещата? Спазването на определени правила е добро начало. Всеки език за програмиране има свои собствени конвенции, какво трябва да се пише с главни букви и какво не. Дали да използвате camelCase, snake_case, kebab-case или нещо друго.
След това има правила, които идват от обектно-ориентираното програмиране. Класовете са съществителни, защото представляват обекти, методите са глаголи, тъй като правят неща. Но с интерфейсите нещата стават трудни. Има различни конвенции за интерфейси. Някои ги поставят като префикс с I— IList, други предлагат суфикс с -able или -ing — Equatable, ProgresReporting. Първото ми предложение за това е да следвате конвенциите в кодовата база, върху която работите. Ако имате опция за избор, тогава ще ви предложа да премахнете всички префикси „I“ или всякакви суфикси „Протокол“ или „Интерфейс“ и да ги наименувате, както бихте нарекли всеки тип. Идеята на интерфейсите е да скрият имплементацията, така че имплементиращият тип трябва да излезе с добро име.
Освен конвенциите, нещо, което ще помогне много, е използването на имена на английски с правилен правопис. Повечето езици за програмиране поддържат Unicode знаци, като някои дори ви позволяват да използвате емотикони за променливи и функции. Така че може да изглежда готино и изкушаващо да дефинирате функцията за журнал по този начин:

Log.⚠️("Warning")
// instead of
Log.warning("Warning")

Но в дългосрочен план ще видите, че това не е много практично. Автоматичното завършване на IDE ще бъде по-трудно за използване. Търсенето във вашия код също ще стане по-трудно. Съвременните IDE имат проверка на правописа, така че просто я активирайте, всеки ще бъде благодарен следващия път, когато се опита да намери нещо кодово за акаунти (а не акаунти 😁)

Съвет 1: Запознайте се с конвенциите за именуване и ги следвайте

В допълнение към конвенциите има няколко други съвета, които мога да предложа.
Не кодирайте информация за типа в името. Имаше моменти, когато имената бяха ограничени по дължина и IDE не предоставяха толкова много контекст и неща като унгарска нотация бяха добри практики. Но сега те не са необходими. Име като accountList не дава допълнителна информация, която не можете да видите на пръв поглед. Просто акаунти е по-кратък и дава достатъчно контекст — колекция от Акаунт. Когато трябва да го използвате, IDE ще покаже какъв е действителният му тип и ще предложи подходящи методи.
Не разчитайте на коментари, за да обясните име. Вместо това се опитайте да измислите по-добро име. Ще разгледаме тази тема в следващия раздел.
Вземете под внимание контекста. „Щат“ може да означава едно нещо в контекста на адрес, състояние в страна като САЩ или Индия или съвсем различно нещо е контекстът на състояние на обект.

И най-важният съвет, който мога да дам за имената е, че те трябва да разкриват намерение. За какво е предназначено да се използва или прави това нещо? Което знам, че звучи по-лесно, отколкото всъщност е. Измислянето на такива имена отнема повече време или може да изисква няколко повторения на преименуване на нещо. Но започнете да го следвате и ще видите, че резултатът си заслужава. Четенето на кода ще започне да има повече смисъл.

Съвет 2: Имената трябва да разкриват намерението

Коментари

Всички сме виждали коментари като този:

// Get primary accounts with non zero balance
accounts.stream()
    .filter(account -> account.isPrimary() && !BigDecimal.ZERO.equals(account.getBalance()))
    .collect(Collectors.toList());

Каква информация ни дават? Нищо повече от това, което можете да научите от четенето на кода. Някои от вас може да кажат - когато видя такъв коментар, няма да прочета кода, защото той казва какво прави. Но ще се доверите ли на коментара. Със сигурност няма да го направя. Виждал съм повече от достатъчно примери, при които кодът е променен, а коментарът не е. Всичко, което прави, е да внесе повече шум и в най-лошия случай може дори да разпространи дезинформация и объркване. Така че коментарите всъщност могат да влошат кода.

Не трябва да използваме коментари, за да обясняваме лош код. Ако смятате, че имате нужда от коментар, тогава помислете за пренаписване на вашия код с по-добри имена и по-кратки функции.

Не коментирайте части от кода си и ги живейте така. Просто ги изтрийте. Имаме системи за контрол на версиите като GIT и SVN, ако трябва да видите предишни версии. Също така имайте предвид коментарите TODO. Не всичко може да бъде изпълнено наведнъж, но също така напускането на TODO не означава, че сте свършили работата си и носи друга отговорност да я завършите.

Това, за което трябва да използвате коментарите, е да обясните намерението си. Защо се пише нещо, а не какво се пише. Първото е ясно от кода.

Съвет 3: Коментарите не трябва да обясняват какво прави кодът, а защо го прави

Функции

Всички ние сме били изгубени в четенето на функция от 100 реда. По средата забравяте какво се случва 20 реда по-горе. Или имаше толкова много вложени изрази if-else, че вече не знаете кой завършва с конкретна затваряща скоба. Съвременните IDE помагат много, те подчертават двойки скоби и позволяват свиване на цели изрази. Но това не е извинение да пишете такъв код.

Единият най-важен съвет, който можете да следвате относно функциите, е да ги поддържате малки. Ако се огледате в интернет, повечето хора ще останат, че не трябва да ви отнема повече от минута или две, за да разберете какво прави функцията. Разделянето на дълги функции на по-къси помага много за четливостта и разбираемостта на вашия код. И ако сте чували за дълбоки стекове от повиквания и се тревожите за намаляване на производителността, не трябва. Ако имате такива ограничения, ще го знаете :) За останалите просто се опитайте да поддържате функциите кратки и в най-добрия случай правете едно нещо. Или казано с термини „SOLID“, имайте една отговорност. Следването на този съвет също ще улесни назоваването. Защото, ако функцията ви прави едно нещо, измислянето на добро име няма да е толкова трудно.

Вторият съвет, който мога да дам относно функциите, е да избягвате странични ефекти.

Страничните ефекти са като неспазени обещания. Вашата функция казва, че ще направи едно нещо, но също така прави нещо друго. Има скрита тайна. И ако не внимавате, когато го четете, може да не го забележите. Или може би можете да добавите коментар, обясняващ тази тайна? Не, не трябва да правите това. Коментарите не компенсират лошия код. Пренапишете функциите си, така че да нямат странични ефекти и да изпълняват това, което обещават.

Съвет 4: Поддържайте функциите кратки и без странични ефекти

Последният ми съвет ще бъде малко по-общ. Става дума за това да ви помогнем да останете в добра форма. Можете да направите това, като следвате не само конвенциите за именуване, но и добрите практики за кодиране и модели на проектиране. Наистина се надявам, че вече има такива във вашия код и ако не, можете да го обсъдите с колегите си и да ги представите. Опитайте се да запазите нещата прости и да намалите сложността. И накрая, вероятно сте чували за правилото на момчетата. Винаги оставяйте кода, който променяте, в по-добра форма, отколкото е бил преди това.

Съвет 5: Бъдете добър гражданин или момче скаут ;)

Това бяха моите топ 5 съвета как да напишете чист код, който е лесен за разбиране от другите и вашето бъдеще. Надявам се, че сте съгласни с някои или всички от тях. Или може би вече ги следвате. Ще се радвам да чуя вашите мисли в коментарите.

Препратки:
Робърт С. Мартин — Чист код: Наръчник за изработване на гъвкав софтуер
Насоки за проектиране на Swift API — https://www.swift.org/documentation/api-design-guidelines/< br /> Цитат: https://www.goodreads.com/work/quotes/3779106-clean-code-a-handbook-of-agile-software-craftsmanship-robert-c-martin
Представено изображение Идентификационни данни: https://www.pexels.com/@kevin-ku-92347