Простые, но эффективные протоколы, которым вы сможете следовать в 2021 году

«Код никогда не лжет, иногда лгут комментарии». - Рон Джеффрис

Комментирование кода! Некоторые люди говорят, что это некрасиво, некоторые говорят, что это нормальная и хорошая практика.

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

Здесь я перечислил 4 простых протокола, которым нужно следовать при написании комментариев.

Хотя эти предложения можно применить к любому языку программирования, мы будем использовать JavaScript, чтобы проиллюстрировать их на практике.

1. Комментируйте только те элементы, которые имеют сложную бизнес-логику.

«Комментарии - это извинение, а не требование. Хороший код в основном документирует сам.

Ниже один выглядит хреново.

function hashIt(data) {
  // The hash
  let hash = 0;

  // Length of string
  const length = data.length;

  // Loop through every character in data
  for (let i = 0; i < length; i++) {
    // Get character code.
    const char = data.charCodeAt(i);
    // Make the hash
    hash = (hash << 5) - hash + char;
    // Convert to 32-bit integer
    hash &= hash;
  }
}

Намного лучше

function hashIt(data) {
  let hash = 0;
  const length = data.length;

  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    hash = (hash << 5) - hash + char;

    // Convert to 32-bit integer
    hash &= hash;
  }
}

2. Удалить мертвый код.

Контроль версий существует не просто так. Оставьте старый код в своей истории.

doStuff();
// doOtherStuff();
// doSomeMoreStuff();
// doSoMuchStuff();

Вместо

doStuff();

3. Удалите комментарии из журнала, вот что Git logs are for

Помните, используйте контроль версий! Нет необходимости в мертвом коде, закомментированном коде и особенно в журнальных комментариях. Используйте git log, чтобы получить историю!

/**
 * 2016-12-20: Removed monads, didn't understand them (RM)
 * 2016-10-01: Improved using special monads (JP)
 * 2016-02-03: Removed type-checking (LI)
 * 2015-03-14: Added combine with type-checking (JR)
 */
function combine(a, b) {
  return a + b;
}

Так может хорошо выглядеть. Очевидно!

function combine(a, b) {
  return a + b;
}

4. Позиционные маркеры? Удалить их

Обычно они просто добавляют шума. Пусть имена функций и переменных вместе с правильным отступом и форматированием придают визуальную структуру вашему коду.

Полный беспорядок

////////////////////////////////////////////////////////////////////////////////
// Scope Model Instantiation
////////////////////////////////////////////////////////////////////////////////
$scope.model = {
  menu: "foo",
  nav: "bar"
};
////////////////////////////////////////////////////////////////////////////////
// Action setup
////////////////////////////////////////////////////////////////////////////////
const actions = function() {
  // ...
};

А теперь давайте немного приберемся

$scope.model = {
  menu: "foo",
  nav: "bar"
};
const actions = function() {
  // ...
};

Это письмо было вдохновлено репо на GitHub.

Поздравляю с кодированием и с Новым 2021 годом!