Как на самом деле писать комментарии к коду — современный учебник по JavaScript

внешний интерфейс JavaScript

Примечания

Как и мыструктура кодаКак мы узнали из этой статьи, аннотации могут быть в виде//Однострочный комментарий, начинающийся или/* ... */Многострочные комментарии к структурам.

Обычно мы используем комментарии, чтобы описать, как и почему работает код.

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

плохой комментарий

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

// 这里的代码会先做这件事（……）然后做那件事（……）
// ……谁知道还有什么……
very;
complex;
code;

Но в хорошем коде количество таких «поясняющих» комментариев должно быть минимальным. Строго говоря, код должен быть понятным и без них.

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

Репецт: Функция разложения

Иногда лучше заменить фрагмент кода функцией, например:

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {

    // 检测 i 是否是一个质数（素数）
    for (let j = 2; j < i; j++) {
      if (i % j == 0) continue nextPrime;
    }

    alert(i);
  }
}

Лучший вариант с использованием факторизованной функцииisPrime:

function showPrimes(n) {

  for (let i = 2; i < n; i++) {
    if (!isPrime(i)) continue;

    alert(i);  
  }
}

function isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) return false;
  }

  return true;
}

Теперь мы можем легко понять код. Сама функция становится комментарием. Этот код называетсясамоописаниекод.

Рецепт: Создать функцию

Если у нас есть длинный блок кода, подобный следующему:

// 在这里我们添加威士忌（译注：国外的一种酒）
for(let i = 0; i < 10; i++) {
  let drop = getWhiskey();
  smell(drop);
  add(drop, glass);
}

// 在这里我们添加果汁
for(let t = 0; t < 3; t++) {
  let tomato = getTomato();
  examine(tomato);
  let juice = press(tomato);
  add(juice, glass);
}

// ...

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

addWhiskey(glass);
addJuice(glass);

function addWhiskey(container) {
  for(let i = 0; i < 10; i++) {
    let drop = getWhiskey();
    //...
  }
}

function addJuice(container) {
  for(let t = 0; t < 3; t++) {
    let tomato = getTomato();
    //...
  }
}

Опять же, сама функция может сказать нам, что произошло. Аннотировать негде. И структура кода после разделения тоже лучше. Очень ясно, что каждая функция делает, что нужно и что возвращает.

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

хорошая заметка

Так что с пояснительными записками вообще плохо. Итак, какая аннотация хороша?

описать архитектуру : Общий обзор компонентов на высоком уровне, их взаимодействия, как выглядит поток управления в различных ситуациях... короче говоря, взгляд на код с высоты птичьего полета. Существует высокоуровневая архитектурная диаграмма, предназначенная для построения кода, специального языка программирования, который интерпретирует код.UML. Определенно стоит учиться.

Аргументы и использование функции ведения журнала: существует синтаксис, предназначенный для функций ведения журнала.JSDoc: использование, параметры и возвращаемое значение.

Например:

/**
 * 返回 x 的 n 次幂的值。
 *
 * @param {number} x 要改变的值。
 * @param {number} n 幂数，必须是一个自然数。
 * @return {number} x 的 n 次幂的值。
 */
function pow(x, n) {
  ...
}

Такая аннотация может помочь нам понять назначение функции и использовать ее напрямую и правильно, не изучая ее внутренний код реализации.

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

Конечно, есть и некоторыеJSDoc 3Такой инструмент может напрямую генерировать HTML-документы с помощью комментариев. ты сможешьusejsdoc.org/Узнайте больше о JSDOC.

Почему задача решается именно так: Важно, какой код пишется. но почемуНе делайтеНаписание таким образом, вероятно, более важно для понимания того, что происходит. Почему задача решается именно так? Код не дает ответа.

Если есть много способов решить эту проблему, почему именно этот? Особенно когда это не самое очевидное.

Без такой аннотации может произойти следующее:

  1. Вы (или ваш коллега) открываете код, который вы написали некоторое время назад, и видите, что это не самый идеальный способ его реализации.
  2. Вы думаете: «Какой же я тогда был глупый, я такой умный сейчас» и переписываете это «нагляднее и правильнее».
  3. ...желание переписать это хорошо. Но в процессе переписывания вы обнаружите, что «более очевидное» решение на самом деле ошибочно. Вы даже смутно помните, почему это произошло, ведь вы уже давно пытались это сделать. Так вы восстановите правильную реализацию, но потеряете время.

Аннотация решения очень важна. Они могут помочь вам продолжать развиваться в правильном направлении.

Каковы некоторые интересные особенности кода? Где они используются: Если в коде есть какие-то изящные и неочевидные способы, он обязательно нуждается в комментариях.

Суммировать

Одним из признаков хорошего разработчика являются его комментарии: их наличие или даже их отсутствие (примечание).

Хорошие комментарии позволяют нам лучше поддерживать наш код и более эффективно вернуться к эффективной разработке кода через некоторое время.

Аннотируйте их:

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

Избегайте комментариев:

  • Опишите, «как работает код» и «что делает код».
  • Избежать под кодом или кодами было достаточно просто, чтобы иметь хороший описательный случай без комментариев, а также написал некоторые ненужные комментарии.

Комментарии также используются в некоторых инструментах автоматической генерации, таких как JSDoc3: они читают комментарии и генерируют HTML-документацию (или другие форматы).

Эта статья была впервые опубликована в общедоступной учетной записи WeChat «Technology Talk». Добро пожаловать в WeChat, ищите и подписывайтесь, и подписывайтесь на более интересный контент.

Учебники по современному JavaScript: учебные пособия по современному JavaScript с открытым исходным кодом, от начального до продвинутого.Рекомендовано официальной документацией React, учебным пособием по JavaScript вместе с MDN..

Читайте онлайн бесплатно:zh.javascript.info

Отсканируйте приведенный ниже QR-код, подпишитесь на общедоступную учетную запись WeChat «Technology Talk» и подпишитесь на более интересный контент.

Категории