Това е втората ми публикация за широко дефиниран чист код. Ако сте пропуснали първия, който е за коментари, тогава можете да го намерите тук. Докато в тази публикация можете да прочетете за друг фактор, който влияе върху качеството на кода на разработчиците: именуването. Ще ви дам широко описани списъци със задачи и не задачи по отношение на текущата тема.

Добрите практики за наименуване имат значително значение за чистия код. Това е така, защото разработчиците трябва да наименуват почти всичко, което е част от кода. Те назовават пакети, класове, променливи, функции и т.н.. Както можете да видите, това е причината наименуването да е толкова важно нещо за поддържане на кода чист. Както споменах, подготвих два списъка. Първият се нарича „TODOS“ и е за неща, които трябва да направим по отношение на именуването. Вторият нарекох „NOT TODOS“ и разбира се е съответно за нещата, които не трябва да правим.

ТОДОС

Използвайте имена, които изразяват добре намеренията

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

  • За каква цел се използва?
  • Какво прави?
  • Как може да се използва?

Ако отговаря на тях, няма няма нужда от допълнителни коментари в кода (от предишна публикация вече знаете, че като цяло коментарите не са добра идея).

Да приемем, че искате да назовете променлива за разстояние, измерено в метри. Не го наричайте distance, meters или m и така нататък. Много по-добре ще бъде distanceInMeters. Ще ви даде ясен контекст и намерения, които тази променлива трябва да изрази. Липсата на тези ценности е голям проблем.

Създайте имена, които се различават ясно

Никога не е добра идея да използвате едни и същи или подобни имена за различни цели. Не можем да видим ясна разлика между това, което се крие под тези имена. Да вземем имена на методи за пример. Наименуването на два метода getProduct(UUID id) и getProductInfo(UUID id) добра идея ли е? Не, защото не знаем за какво е тази малка разлика. Принудени сме да проверяваме какво връщат и какъв код се изпълнява в тях. Разбира се, в този пример имаме комфорт поради факта, че те наистина връщат нещо. Ако не, ще бъде още по-трудно да се забележи разликата.

Друг пример е използването на числа за номериране на променливи, които имат едно и също име, напр. product1, product2 и така нататък. Въпреки това, такива имена не са подвеждащи, но все пак неинформативни.

Създайте имена, които можете да произнасяте

Без съмнение, използването на умствени преки пътища или група от букви, които не образуват съществуваща дума, е саботаж по отношение на яснотата на кода и като цяло на цялото процес на развитие. Поради това използването на името getModStrNm за метод вместо getModifiedStreetName не е добра идея. Само си представете колко забавен би изглеждал разговорът ви с друг разработчик, ако и двамата трябваше да говорите за този метод. Да не говорим за трудността при четене и разбиране на кода, което всъщност все още е основен проблем за непроизносимите думи.

Използвайте имена, лесни за търсене

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

Добра практика е да декларирате статични променливи в горната част на класовете. Да кажем, че правим статична променлива с име MIN_LETTERS_PER_DAY равна на 3. Благодарение на това ще бъде по-лесно да намерите тази променлива с функция за търсене. Но има още една причина за тази практика - ако се окаже, че тази стойност трябва да е равна на 4, тогава всичко, което трябва да направите, е да промените 3 на 4 на едно място, вместо на всяко място, където тази стойност беше използван.

Използвайте глаголи в имената на методите

Името на методите трябва да е от глаголи или отглаголни съществителни като activateAccount или accountActivation, точка. Нещо повече, методите, които са аксесоари, мутатори или предикати, трябва да бъдат създадени на базата на оперирана стойност като getExpirationTimestamp, setName и isActive.

Използвайте една дума за концепция

Разработчиците трябва да се придържат към един и последователен лексикон за проекта. Използването на различни имена за аналогови методи в различни класове не е оптимално решение. Например, не трябва да използвате get, fetch и retrieve взаимозаменяемо. Значенията на тези имена са малко различни, така че могат да предизвикат у други разработчици съмнение във факта, че тези методи извършват точно едни и същи операции. Така че, както можете да видите, спазването на това правило е наистина важно за качеството на нашия код, тъй като това как вашият код е разбираем от другите е огромен фактор за крайното качество.

Използвайте имената на домейните на решението и проблема

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

Добавете важен контекст

Обичайно е, че няма възможност да се назове даден елемент по някакъв рационален начин от гледна точка на придаването му на достатъчен контекст. Но с помощта идва правилното наименуване на тези компоненти, в които е нашият елемент (като класове или методи). Наименувайте ги по такъв начин, че те също да могат да донесат необходимата информация и по някакъв начин да го освободят от част от отговорността за предоставяне на достатъчен контекст. Да кажем, че имате клас Foo и той е отговорен за нещо напълно различно от метода, който искате да създадете в този клас. Този метод ще бъде напр. извършване на истинско телефонно обаждане с помощта на библиотека на трета страна и то ще бъде наречено makePhoneCall(String from, String to). Въпреки факта, че класът Foo не трябва да има внедрени методи, които изобщо не са свързани с него, има възможност да го преименувате в make(String from, String to) благодарение на преместването му в новосъздадения клас, наречен PhoneCall. Тогава клас Foo може просто да извика нещо подобно: PhoneCall.make(“+48123456789”, “+48987654321”) ако този метод е статичен, разбира се. Между другото, има още едно предимство от това - когато имате PhoneCall клас, можете да разделите тялото на нашия метод на няколко метода, за да направите нещата по-ясни и разбираеми.

НЕ ТОДОС

Избягвайте дезинформацията

В един от предишните съвети писах за даването на имена, които представляват добър контекст. В това искам да предупредя за именуване, което дава лош или неясен контекст. По мое мнение дори е по-лошо от това изобщо да не се дава контекст. Подобно поведение дезинформира всички, които работят с нашия код и дори самите нас. Прост пример: да кажем, че имате карта, която е колекция от някои продукти. Даването на име на тази колекция productsList просто предполага, че тази колекция не е карта, а списък. Това беше просто прост пример, но нещата може да станат по-сериозни, когато замените име insert за метод с save.

Не използвайте префикси

Ако все още използвате префикси в имената на променливите на екземплярите, тогава можете да спрете веднага. В края на краищата, ние всички използваме IDE, които са в състояние да оцветят всеки елемент от кода по неговия тип. Благодарение на това префиксите са просто безполезен шум в кода, който си струва да се елиминира. От моите наблюдения мога да кажа, че разработчиците пренебрегват тези префикси, когато става въпрос за четене на такъв код, но защо ги прави трудни за живеене?

Избягвайте умствените изображения

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

Не използвайте глаголи в имената на класовете

Това е противоположен съвет на този за имената на методите. Вие не трябва да използвате глаголи в имената на класовете. Вместо тях трябва да използвате съществителни или съществителни изрази. Освен това не трябва да използвате твърде общи имена като Parser или Generator. Би било хубаво да се спомене в тези имена какво могат да анализират или генерират.

Не бъди смешен

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

Не правете каламбури

Това е аналог на съвета за използване на една дума за понятие, но обратното. Винаги трябва да използваме само едно име за идентични операции или значения. Ще бъде по-лесно да се обясни с пример. Да кажем, че имаме няколко класа и във всеки от тях има точно един метод, който прави същото като останалите. Изглежда очевидно, че всеки метод трябва да има едно и също име. Всичко е наред, но когато трябва да направим още един клас, който също трябва да има имплементиран такъв метод и този път този метод трябва да извърши малко по-различна операция, може да имаме проблем. В тази ситуация може да възникне изкушение този метод да се наименува точно по същия начин като в други класове. За съжаление бихме направили игра на думи, ако се откажем, и искаме кодът ни да бъде възможно най-разбираем и да не е труден за изучаване, нали?

Не добавяйте твърде много контекст

В тази публикация вече писах за необходимостта от добавяне на контекст чрез правилно даване на имената за класове и методи. Поради това не трябва да прекалявате с добавянето на твърде много контекст за елементи, които са част от тях. Става ненужно, защото вече го знаем от останалата част от кода. Например, когато имаме прост DTO клас UserDto, тогава не е нужно да използваме думата user във всяко име на променлива в този клас. Никой няма да има съмнения, че променливата id е потребителският идентификатор, тъй като тя вече произтича от контекста, даден от името на UserDto клас.

Резюме

Лично аз не веднъж се натъквах на случаи на нарушаване на горните правила. Това, което е интересно, беше най-вече, когато работех върху проектите за Android. Мисля, че причината е, че мобилните проекти обикновено са много по-малки от бекенда. Често само един човек работи върху мобилното приложение, така че той смята, че не трябва да обръща толкова много внимание на чистотата на кода. За съжаление, рядко се случва проектът за Android да бъде разработен от началото до края от една компания и по този начин друг разработчик трябва да се сблъска с кода на някой друг. Бях този друг разработчик повече от веднъж. След това видях някои смесени имена за едни и същи елементи от кода, някои шеги, а също и много дезинформативни контексти. Тези проблеми често са трудни за коригиране, тъй като изискват много време, за да ги разберете първо и едва тогава можете да започнете с рефакторинг.

Както в първия пост, напомням ви, че съдържанието на този също е базирано на книгата Clean Code: A Handbook of Agile Software Craftsmanshipна Робърт К. Мартин. Надявам се, че в тази публикация съм ви дал широк и полезен набор от съвети относно именуването в програмирането. Най-добре би било да се придържаме към всички тях, но мисля, че най-важното нещо е да помним, че кодът, който пишем, не е само за нас, но и за другите. И с това страхотно заключение можем да приключим тази публикация, но преди това бих искал да изразя интереса си към вашето мнение. И така, има ли други добри или лоши навици, на които сте се натъкнали или прилагате? Насърчавам ви да помислите върху това и да споделите мислите си, като оставите коментар.