Документальні коментарі, чеською чи англійською мовою?

22. 08. 2019

Obsah článku

Написання документації займає багато часу і часто після вас її ніхто не читає, тому гарною практикою є написання коментарів безпосередньо у вихідному коді. Однак велика кількість тексту невиправдано захаращує код, який потім може не поміститися на моніторі одночасно, що знову ж таки знижує його читабельність.

Тому будь-який код повинен бути зрозумілим, тобто при його читанні повинно бути одразу зрозуміло, що він робить, і робити він повинен тільки одне.

Наприклад, якщо функція має назву getUserProfileById($id), то абсолютно зрозуміло, що така функція робить і якого значення повернення ми можемо очікувати. Саме тому коментарі часто використовуються для опису лише вхідних та вихідних параметрів + коротке текстове пояснення принципу (якщо відбувається щось більш складне). Якщо код призначений для кількох людей, ввічливо вказувати автора і дату створення.

/**
 * Повертає значення TRUE, якщо передане значення є дійсною IPv6-адресою
 * Альтернативний регулярний вираз:
 * /^(((?=(?>.*?(::))(?!.+\3)))\3?|([\dA-F]{1,4}(\3|:(?!$)|$)|\2))
   (?4){5}((?4){2}|((2[0-4]|1\d|[1-9])?\d|25[0-5])(\.(?7)){3})\z/i
 * @автор Ян Барасек
 */
function isIpV6(string $value): bool
{
   if (str_contains($value, ':')) {
      return (bool) filter_var($value, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6);
   }

   return false;
}

З коментаря одразу зрозуміло, що функція очікує на вхід IPv6-адресу і повертає булеве значення TRUE або FALSE в залежності від того, як пройшла перевірка.

Анотація bootstrap використовується для позначення значень за допомогою стандартизованих ключів, які багато редакторів можуть обробляти далі і, наприклад, підказувати параметри при виклику функції або передавати залежності автоматично.

Коментарі безпосередньо всередині коду використовуються лише в особливих випадках. Якщо код потребує внутрішнього коментаря, це, як правило, свідчить про те, що його слід розбити на декілька менших частин, які будуть звертатися до своєї частини програми.

Мови

Класи, методи, функції та змінні прийнято завжди називати англійською мовою (щоб зробити код читабельним для великої кількості програмістів), клавіші відносно стандартизовані з єдиним синтаксисом, тому там мова також не має значення, а для довідкового тексту це залежить від використання проекту. Якщо це невеликий проект для стабільної команди людей, то англійська мова не обов'язково є проблемою, навпаки, принаймні всі чудово розуміють опис.

Мотивація до використання анотації

Спеціальні символи (позивні) можуть бути помічені іншими інструментами за межами редактора, тому корисно, наприклад, розміщувати її тести (на яких входах я очікую який вихід) безпосередньо над визначенням функції, таким чином ніколи не забуваючи місце, де написані тести і в той же час кожен програміст відразу має уявлення про те, що робить функція.

Ось невеликий приклад того, як може виглядати визначення тесту (це лише концепція нотації, а не конкретний інструмент тестування):

Dosadí hodnoty a vynutí jejich dump do prohlížeče / konzole:
@test Název I---> $limit => {1-{5-8}}, $city => {Praha|Kladno|Brno|Plzeň} O---> [DUMP]

Vygeneruje náhodný hash o délce 6 znaků a ověří, zda je hlavička odpovědi jakákoli, kromě 201:
@test Název I---> $hash => {a-z0-9|len:6} O---> [HEADER:***|!HEADER:201]

Vygeneruje dvojici čísel a na výstupu ověří jejich součet:
@test Sčítání čísel I---> $a => {1-5}, $b => {7-12} O---> ($return == $a+$b)

Načte náhodný článek s ID mezi 1 až 30, ověří jeho délku nebo neprázdnost:
@test Získání textu článku I---> $id => {1-30} O---> (strlen($return) > 64 || $return != NULL)

Vygeneruje náhodnou IP adresu a ověří, zda je z České republiky:
@test Geolokace I---> $ip => {1-255}.{1-255}.{1-255}.{1-255} O---> ($return['країна'] == 'EN')

Pokusí se načíst článek s vysokým ID a při testování mrkne na modifikátory (filtry):
@test Neexistující článek I---> $id => {1000000+} O---> [HEADER:4**:3**|NOCONTENT]

Vrátí počet rohů jednorožce:
@test Jednorožec I---> $maRohy => TRUE O---> 1

Kolik prstů ukazuji?
@test Prsty I---> $ukazuji => {0-10|NAME:prsty} O---> ($return == {*|NAME:prsty})

Яка взагалі була б написана, наприклад, за правилом:

@test <název_testu> I---> $<proměnná> => <hodnota> O---> [<modifikátor>:<hodnota>] (<výraz_platnosti>)

Усередині тестів я використовував генератор випадкових величин з використанням регулярних виразів. Наведу кілька прикладів:

{<hodnota><směr_nerovnosti>}           {500+}  {250-}   {-200-(-50)}
{<začátek>-<konec>}                    {0-5}   {a-z}   {a-f0-9}
{<Hodnota1>|<Hodnota2>|<Hodnota3>}     {Praha|Kladno|Brno}
{<výraz>|<modifikátor>:<hodnota>}      {a-z0-9|len:6}  {*|len:6}
{*|<modifikátor>:<hodnota>}            {*|randomWord:5}

Jan Barášek Více o autorovi

Autor článku pracuje jako seniorní vývojář a software architekt v Praze. Navrhuje a spravuje velké webové aplikace, které znáte a používáte. Od roku 2009 nabral bohaté zkušenosti, které tímto webem předává dál.

Rád vám pomůžu: