Нужно ли комментировать свой код?

Я выделил три разных типа комментариев, и во всех случаях есть хорошие и плохие примеры. Итак, вот они.

Тип 1. Комментарии к документации

Это специальные комментарии, используемые для документирования кода. Обычно они записываются в определённом формате с целью предоставления дополнительной информации о контексте.

Эти типы комментариев довольно распространены в конфигурациях Laravel.

config/sanctum.php:

/*
|--------------------------------------------------------------------------
| Stateful Domains
|--------------------------------------------------------------------------
|
| Requests from the following domains / hosts will receive stateful API
| authentication cookies. Typically, these should include your local
| and production domains which access your API via a frontend SPA.
|
*/

'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort()
))),

Они также могут включать примеры, как в библиотеке Lodash.

_.partition([1, 2, 3, 4], n => n % 2);

// → [[1, 3], [2, 4]]

Другая категория комментариев к документации называется аннотациями и используется такими инструментами, как Swagger, для создания документации или предоставления дополнительного контекста для IDE.

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */

Для обеспечения согласованности комментарии к документации должны соответствовать одному и тому же стандарту.

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

Тип 2. Уточняющие комментарии

Они используются для объяснения запутанного или сложного участка кода. Они призваны предоставить дополнительный контекст, чтобы помочь разработчикам легче понять код, особенно если код был написан некоторое время назад.

Хороший пример

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

function addMapEntry(map, pair) {
  // Don't return `map.set` because it's not chainable in IE 11.
  map.set(pair[0], pair[1])
  return map
}

Плохой пример

В этом случае комментарий излишен, а код достаточно понятен.

// Finds user by id and assigns it to a variable $user
$user = User::find($id);

Этот комментарий не связан с кодом. Бесполезная попытка объяснить, какой там может быть код.

// If $roleId doesn't exist admin can create a new role
User::roles()->attach($roleId);

Ещё один случай неправильного использования комментариев — когда пытаются документировать плохо написанный код. Могли бы вы рассказать, что делает эта функция, если бы не комментарий. Но, даже комментарий не сообщает, что это за выражение 22/7 (приблизительное значение числа π в виде дроби.)

/**
 * Calculates the volume of a cylinder
 * $a is the radius
 * $b is the height
 */
function ccv($a, $b)
{
    return $a * $a * $b * 22 / 7;
}

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

function getCylinderVolume($radius, $height)
{
    return pi() * $radius ** 2 * $height;
}

Сразу выглядит лучше, правда?

Тип 3. Весёлые комментарии

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

Хороший пример

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

// Dear maintainer:
//
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 42

Код Laravel также содержит более сложные забавные комментарии. Как заметил Caleb Porzio:

Одной из моих любимых вещей в Laravel всегда были навязчивые трёх строчные комментарии Тейлора к коду (те милые маленькие комментарии, где каждая строка ровно на три символа короче предыдущей).

/*
|-----------------------------------------------------------------------------
| How to write your code comments like Taylor:
|-----------------------------------------------------------------------------
|
| In Laravel, there are 598 three-line code comments. The first line of each
| is ~74 characters long. Each subsequent line has three characters fewer
| than the one above it. Whether trailing periods count is your choice.
|
*/

Плохой пример

Что ж, это может быть забавным, если это не ваш код, из-за которого весь код выглядит непрофессионально.

// This code sucks

Заключение

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

Какие ещё забавные или плохие примеры комментариев вы встречали в дикой природе?