Комментарии к коду: как правильно сказать "почему", а не "что"

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

Мне самому объяснили всю глубину комментариев в коде одной фразой: "Комментарий оставлен не для того, чтобы объяснить, что я написал, а для того, чтобы ты понял, почему я это тут написал". И уже после, со стажем работы, отмечая хорошие и плохие проекты в плане читаемости и информативности кода, я убедился, что фраза довольно точно описала рецепт полезного, грамотного комментария. 

Но давайте лучше возьмём пример кода, когда комментарий отвечал на вопрос "что?", ведь чем нагляднее тем лучше:

struct GroupLink {
    // идентификатор ссылки
    let id: String

    // дата отправки
    let date: Date

    // последовательность ключа
    let sequence: String
}

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

Теперь рассмотрим пример, когда комментарий ответил на вопрос "почему?":

struct GroupLink {
    let id: String
    let date: Date
    let sequence: String

    // Данные ссылки перестают быть действительными после 25 использований
    let linkUseCharges = 25
}

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

Вообще, комментировать зачастую стоит лишь некии аномалии, отклонения от стандартного кода вашего проекта, когда стороннему разработчику может потребоваться пояснение, почему такое отклонение было необходимо. И всё же, не стоит жалеть комментарии на значительные изменения, чтобы не оставить вопрос "почему" вовсе без ответа.

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

Теперь, рассмотрим ещё одно неверное использование комментариев. Сперва я приведу пример с таким использованием, а в рамках некого интерактива вы постараетесь понять, какая же ошибка допущена разработчиком с кодовым именем Альфредо:

// Убеждаемся, что пользователю можно предоставить доступ к контенту из подписки
if user != nil && user.accessLevel = .premium && user.activeConnections < 4 {
     ...
}

Кажется, Альфредо всё сделал верно. Перед выдачей доступа действительно необходимо убедиться в соответствии паре свойств, и, чтобы было понятно зачем эти проверки, он и оставил комментарий.

Что же здесь не так?

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

let canUserAccessPremiumContent = user != nil && user.accessLevel = .premium && user.activeConnections < 4

if canUserAccessPremiumContent {
     ...
}

Теперь, читая код, становиться понятно, для чего сделаны данные проверки, и необходимость в комментарии отпадает.

И в качестве десерта данной статьи, пару слов о зомби-коде. Его легко узнать:

// func iAmSureThisFuncWillBeUsedIn2023 {
//     ...
// }

Кто-то забывает про этот код, кто-то свято верит, что в 2023 он обязательно переиспользует этот метод и сэкономит себе много времени. 

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

Что ж, подведём черту для данной статьи с её основными тезисами.
Комментарии - отличный инструмент, чтобы пояснить отклонения от обычного для вашего проекта кода. Они не должны служить оправданием некорректному наименованию методов и свойств, а также оставлять код про запас, оставаясь конкретным инструментом пояснения. Поэтому, прежде чем оставлять комментарий в коде, убедитесь, что вы поясняете вопрос "почему", а не "что".