Как комментировать, если заявления наиболее читабельны

Question

Я пытаюсь сделать мой код легко понятным для будущих читателей.

У меня всегда были проблемы с тем, как сформулировать мои комментарии if, чтобы сделать его наиболее понятным.

Может быть, это кажется тривиальным, но это всегда беспокоит меня

Вот пример:

if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

Вот как я могу это прокомментировать

// If request doesn't exist
if ( !$request ) {
    // Set request to current request_uri
    $request = $_SERVER['REQUEST_URI'];
}

// Check for a request
if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

// Request doesn't exist
if ( !$request ) {
    // Set request
    $request = $_SERVER['REQUEST_URI'];
}

Не лучший пример, но, как я вижу, есть бесконечные способы выразить это.

Я никогда по-настоящему не работал в команде, поэтому у меня мало опыта, когда другие люди читают мой код.

Что вы думаете о том, как лучше всего сказать, чтобы сделать его читаемым для будущих программистов?

Answer 1

Я согласен с Нилом, для этого примера в любом случае довольно очевидно, что вы проверяете, существует ли запрос. Добавление большого количества комментариев может сделать ваш код менее читабельным. (то есть комментируя каждую строку или каждую другую строку кода)

Answer 2

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

Answer 3

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

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

Answer 4

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