Как сделать комментарии к операторам if наиболее читаемыми

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

У меня всегда были проблемы с тем, как сформулировать комментарии к оператору 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'];
}

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

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

Каковы ваши впечатления от того, как лучше всего сформулировать это, чтобы сделать его читабельным для будущих программистов.


comments language-agnostic
person Community    schedule 03.06.2009    source источник

Ответы (24)


arrow_upward
9
arrow_downward

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

person Community    schedule 03.06.2009
comment
Я немного пофантазирую над этим комментарием: в PHP (его пример выглядел как PHP-код) (! $ Request) мог быть эквивалентен двум вещам: if (! Isset ($ request)) или if ($ request == false ). Другими словами, выражение, оценивающее false, может означать то же самое, и, возможно, это различие важно. В целом согласен с вашим комментарием! Я просто хотел указать, что в этом примере, хотя функциональность может быть очевидной (если есть запрос), комментарии указывают на то, что мы / на самом деле / ​​тестируем! - person poundifdef; 04.06.2009

arrow_upward
9
arrow_downward

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

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

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

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

if (markerIsValid(a, b, c))

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

person Community    schedule 03.06.2009
comment
+1 - извлечение метода не только самодокументируется, но и делает логику многократно используемой и непротиворечивой. - person g .; 03.06.2009
comment
Просто, понятно и понятно, так почему бы и нет .. Спасибо за этот хороший ответ. - person Martin Pfeffer; 01.11.2014

arrow_upward
5
arrow_downward

Моя рекомендация - «не заявлять об очевидном».

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

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

person Community    schedule 03.06.2009

arrow_upward
4
arrow_downward

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

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

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

person Community    schedule 03.06.2009

arrow_upward
3
arrow_downward

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

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.
}
person Community    schedule 03.06.2009
comment
Вместо того, чтобы говорить, что запрос еще не установлен, я просто скажу, что запрос еще не установлен. Это потому, что мы уже внутри блока if. Когда мы там, мы знаем результат сравнения, поэтому указываем его как факт, а не как условие. - person Rob Kennedy; 03.06.2009

arrow_upward
2
arrow_downward

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

https://rads.stackoverflow.com/amzn/click/com/0132350882

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

person Community    schedule 03.06.2009

arrow_upward
2
arrow_downward

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

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

См. Код завершен. У МакКоннелла есть отличная глава о комментариях.

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

person Community    schedule 03.06.2009
comment
да, у меня есть эта книга, забыл про раздел комментирования. Благодарность! - person Galen; 04.06.2009

arrow_upward
2
arrow_downward

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

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

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


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

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

person Community    schedule 03.06.2009

arrow_upward
1
arrow_downward

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

person Community    schedule 03.06.2009

arrow_upward
1
arrow_downward

Это во многом зависит от программиста. Дам два совета:

Не говорите очевидного

Возьмем следующий пример:

// If request doesn't exist
if ( !$request ) {

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

Не думайте, что все разработчики знают то, что знаете вы

Посмотрите на свой код и представьте, что вы относительный новичок. Вы бы это поняли? Если нет, поясните в комментариях.

person Community    schedule 03.06.2009

arrow_upward
1
arrow_downward

Я использую эту форму:

// Full Comment
if (condition) {
    action;
    action;
}

Потому что, когда включено сворачивание кода, вы получите что-то вроде этого:

// Full Comment
if (condition) { ...} [+]

Вместо этого:

// Half Comment
if (condition) { ...} [+] <---button to click to get the rest of the comment
person Community    schedule 03.06.2009

arrow_upward
1
arrow_downward

Вы не должны этого делать. Просто выполните рефакторинг, введя поясняющие переменные:

 if ( (platform.toUpperCase().indexOf("MAC") > -1) &&
      (browser.toUpperCase().indexOf("IE") > -1) &&
       wasInitialized() && resize > 0 )
 {
   // do something
 }

становится:

boolean isMacOs     = platform.toUpperCase().indexOf("MAC") > -1;
boolean isIEBrowser = browser.toUpperCase().indexOf("IE")  > -1;
boolean wasResized  = resize > 0;

if (isMacOs && isIEBrowser && wasInitialized() && wasResized)
{
    // do something
}
person Community    schedule 03.06.2009

arrow_upward
1
arrow_downward

Вторая ссылка на 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'];
}

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

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

Пример операторов if достаточно прост и не требует комментариев. Чрезмерное комментирование может быть опасным, потому что тогда вам придется поддерживать не только код, но и комментарии. Для сложных операторов if у вас есть правильная идея - приклейте комментарий прямо над оператором if.

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

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

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

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

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

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

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

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

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

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

Не комментируйте очевидное, если только ваша аудитория, например, начинающие (1).

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

Если ваши переменные правильно названы, ваш оператор if должен быть довольно понятным.

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

Ознакомьтесь с определением «тактических» и «стратегических» комментариев в этом документе http://www.doc.ic.ac.uk/lab/cplus/c++.rules/chap4.html#sect3

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

См. Этот аналогичный / идентичный вопрос: Где размещать комментарии в конструкции IF THEN ELSE

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

Назовите свои переменные / методы так, чтобы комментарий был тривиальным.

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

Если вам нужно прокомментировать свои условные выражения, вы, вероятно, на пути к анти-шаблону стрелок .

Чтобы в этом помочь, используйте рефакторинг составного метода. Убедитесь, что ваши методы / функции инкапсулированы на одном уровне абстракции. Полиморфизм позволит вам полностью избавиться от условных выражений. Это лучше, потому что поведение определяется динамически во время выполнения. Вам придется программировать (и поддерживать) на одну вещь меньше.

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

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

person Community    schedule 03.06.2009

arrow_upward
0
arrow_downward

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

  • обычно легче читать "положительные" условия, чем отрицания (не условие)

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

    function getRequest( $req ) {
    if( isset( $req ) ) {
        return $req;
    } else {
        return $_SERVER['REQUEST_URI'];
    }
}

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

  • должны прочитать :

person Community    schedule 03.06.2009