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

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

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

Я мог бы видеть случай, когда тестовый код сложен:

if (a == 3 && b && c > 2)

но в этом случае я сначала попытался бы извлечь метод со значимым именем:

if (markerIsValid(a, b, c))

Только если бы это было невозможно, я бы прокомментировал тест.

Answer 3

Моя рекомендация: «Не указывайте очевидное».

Чтение if (! $ Request) говорит - если не существует запроса. Мне не нужен комментарий для этого.

Если у вас есть несколько проверок (это || (это && это-тоже)), я бы пошел для создания метода, который возвращает логическое значение с результатом. Тогда ваше имя метода - это ваш комментарий, который обычно лучше, чем реальный комментарий.

Answer 4

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

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

Итог: используйте ваше усмотрение.

Answer 5

Используя ваш пример, я обычно предпочитаю следующий стиль:

if ( !$request ) {
    // The request is not yet set, so retrieve it.
    $request = $_SERVER['REQUEST_URI'];
}

Мне нравится размещать его внутри блока if, чтобы он выглядел лучше, когда есть else или else if.

if ( !$request ) {
    // The request is not yet set, so retrieve it.
    $request = $_SERVER['REQUEST_URI'];
}
else {
    // Comment about doing something else here.
}

Answer 6

Когда я пишу комментарии к коду, я пытаюсь либо

1. Объясните хитрую, неочевидную процедуру (reg ex - прекрасный пример), или
2. Объясните почему Я делаю то, что делаю.

Выезд Код завершен . У Макконнелла есть замечательная глава по комментированию.

Я бы порекомендовал книгу всем, кто пишет код.

Answer 7

Помните: редко когда вам нужны встроенные комментарии, чтобы сказать , что делает код; если вы не объясняете особенно грубый алгоритм, код должен сам нести это бремя без комментариев. (А если это невозможно, возможно, вам придется сделать имена переменных более описательными.)

Однако комментарии, объясняющие , почему код делает то, что он делает, могут быть чрезвычайно ценными. (Предполагая, что это не чертовски очевидно; если это так, просто пропустите комментарий.)

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

<code>
    if ( !$request ) {
        // If the request isn't set, foo() will barf; the current
        // request is a suitable default.
        $request = $_SERVER['REQUEST_URI'];
    }

Просто убедитесь, что ваши комментарии оправдывают их собственное существование, а остальное подливка.

Answer 8

Прочитайте книгу «Чистый код» Роберта Мартина.

http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

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

Answer 9

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

Answer 10

Я вторую ссылку на Code Complete: отличная книга, которую нужно читать для программистов.

Есть несколько вещей, которые я хотел бы иметь в виду:

1. Не повторяйте код : объясните, что он делает в общих чертах.

2. Никогда не предполагайте, что что-то очевидно ; уточнить и объяснить код.

3. Используйте функции, чтобы уточнить ваше значение в зависимости от ситуации: сделайте так, чтобы имя относилось к тому, что делается.

4. Никогда не предполагайте, что код не требует пояснений - даже если так и должно быть. Самое главное, никогда не предполагайте, что тот или иной код «идиома» будет прочитан кем-то, кто его понимает: объясните, что делает код.

Как кто-то сказал, не ведите с отрицательным, если можете: у меня был класс программирования, где отрицательный IF не был разрешен ни при каких обстоятельствах. Если вы действительно застряли, вы можете использовать свой родной язык (например, английский) в своих интересах. Вместо:

if (!eof(f))

Можно сказать:

if (moreData(f))

На вашем примере я бы сказал что-то вроде этого (если я правильно понимаю):

// Make sure that we have a valid request:
// set it if it is not set already
if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

Я бы также добавил: не помещайте комментарии в поля . «Ящик» трудно поддерживать и поддерживать: каждый тратит больше времени на исправление «ящика», вместо того, чтобы поддерживать комментарии текущими.