//Без коментари

Оригиналът е на S. G., който споделя, че пише сорс код, който се старае да усъвършенства дотолкова, че да е подходящ дори и за медиите

20
2376

Коментарите трябва да са около 5% от целия сорс код“ – ми каза веднъж моят колега, който е преподавател по програмиране.

Самият аз, през есента на 2019 година му помагах да водим началния курс по компютърно програмиране и между нас възникнаха разногласия по повод това, дали студентите трябва да добавят коментари в своите проекти, които ние трябваше да проверяваме.

„Аз искам студентите още в самото начало да придобиват полезни навици. Съгласни сте нали, че добавянето на коментари подобрява качеството на кода?“ – попита ме моя колега, малко разстроен от моята негативна реакция.

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

Чакайте малко, какви са тези неща? Коментарите на никого не пречат. Или може би все пак пречат?

Има две причини, поради които лично аз смятам коментарите за отрицателен модел при писането на сорс код:

Първо, те неизбежно остаряват и стават неактуални. Разработчиците забравят да обновяват коментарите след рефакторинга на сорс-кода и при създаването на нови функции. Когато това се случи, тези коментари са първата причина за възникването на тотално объркване. Това е особено вярно за големите компании, в които най-различни екипи от програмисти активно променят общата кодова база. Представете си какво чувства един начинаещ, който не може да разбере, защо домът показан в началното изображение на тази статия има коментар за палмово дърво (Palm Tree).

Второ, програмистите (включително и аз) твърде често пишат излишни, както и лоши коментари. Това съм го забелязал във всяка една компания, в която съм работил, и тази грешка допускат редица превъзходни програмисти. В моя екип в Google имаше правило, че всяко определяне на необходим буфер трябва да бъде предшествано от коментар. Ето защо имахме много сорс код, който изглеждаше по следния начин:

// Represents a Dog.
message Dog {
    // The id of the dog.
    string id = 0;
    // The name of the dog.
    string name = 1;
    // The breed of the dog.
    string breed = 2;
}

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

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

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

В този пример ние изпращаме заплащането на продавачите при изпълнение на точно определени условия. Например, това може да бъде ритейлър в Amazon, който получава общата сума за своите продажби от тази платформа.

# Seller is eligible to be paid under the following conditions:
# 1. It's past 2020/5/1 when we got legal approval to make payouts
# 2. It’s Nov/Dec since those are the only months eligible
# 3. User is not from list of countries that are banned
today = date.today()
if today > date(2020, 1, 1) and (today.month == 11 or today.month == 12) and user.country not in ['Narnia', 'Odan', 'Maldonia']:
    # This function does the actual payout by calling Stripe
    # It saves the response asynchronously.
    payoutHandler()

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

  1. Условията на заплащането. Без коментар в началото читателят програмист самостоятелно би трябвало да разгледа всички подусловия в условния оператор, за да разбере, дали е необходимо да бъде осъществено разплащане.
  2.  Става ясно защо са използвани константите 2020/5/1, 11, 12 и [‘Narnia’, ‘Odan’, ‘Maldonia’] с конкретни значения и какво се обозначава с това.
  3. Какво прави методът payoutHandler().

Нека сега да разгледаме по какъв начин може да бъде пренаписан същия този сорс код, който да подаде същата информация, но без използването на коментари:

PAYOUT_APPROVAL_DATE = date(2020, 5, 1)
BANNED_COUNTRIES = ['Narnia', 'Odan', 'Maldonia']
NOVEMBER, DECEMBER = 11, 12
ELIGIBLE_MONTHS = [NOVEMBER, DECEMBER]
today = date.today()
is_past_approval_date = today > PAYOUT_APPROVAL_DATE
is_eligible_month = today.month in ELIGIBLE_MONTHS
is_user_from_banned_country = user.country in BANNED_COUNTRIES
if is_past_approval_date and is_eligible_month and not is_user_from_banned_country:
 stripe_payout_resp = callStripeToPayout(user)
 saveResponseAsync(stripe_payout_resp)

Обърнете внимание, че информацията която преди това се подаваше с помощта на коментари, сега се предава с помощта на временните променливи is_past_approval_date, is_eligible_month, is_user_from_banned_country, константата BANNED_COUNTRIES, както и с помощта на глаголи в качеството на имена на функциите.

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

Тоест, получава се така, че коментари не трябва никога да се използват? Това не е ли прекалено строго изискване?

Аз използвам следното емпирично правило: да не се използват коментари, отговарящи на въпроса „какво?“. Коментари трябва да се използват, когато трябва да се обясни „за какво?“ и само понякога, когато „за какво?“ не може да се обясни много лесно. В повечето случаи, за да се обясни „за какво?“ е достатъчно правилно да се изберат имената на променливите и константите. Така например, вместо да бъде добавен следния коментар

# This code removes the invalid control characters because the 
# AS400 processor cannot handle them

е достатъчно да бъде създадена функцията:

def remove_AS400_incompatible_control_chars():

Ако при подаването на информацията не може да се разчита на подобното използване на имена – например, ако кодът прави нещо дребно или нещо неочевидно, то тогава разбира се, коментарите са напълно обосновани. Ето някои примери на полезни коментари:

# Prevents a rare but severe race condition which happens when...
# Closing this write transaction before making the RPC to prevent stale locks

Може все пак да си прегледате своите сорс кодове дали няма възможност за замяна на коментарите с код, който ще си остане добре документиран при всякакви промени.

4.6 7 гласа
Оценете статията
Абонирай се
Извести ме за
guest
20 Коментара
стари
нови оценка
Отзиви
Всички коментари