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

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

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

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

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

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

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

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

Answer 2

Не нужно. Просто рефакторинг путем введения объясняющих переменных :

 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
}

Answer 3

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

Не указывайте очевидное

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

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

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

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

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

Answer 4

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

Answer 5

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

Answer 6

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

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

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

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

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

• должен читать:

  • Рефакторинг Мартина Фаулера

  • Запись твердого кода

  • Код завершен

Answer 7

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

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

Если вам нужно прокомментировать свои условия, вы, вероятно, находитесь на пути к Arrow Anti-pattern .

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

Answer 8

См. Этот похожий / идентичный вопрос: Куда добавлять комментарии в конструкции ЕСЛИ-ЛИБО

Answer 9

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

Answer 10

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

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

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