Распутывающий код спагетти: как написать поддерживаемый JavaScript

Как вы разделяете большую функцию с большим количеством тесно связанных логики? Давайте сделаем это вместе.

 // This example uses the Fetch API to request an API. Let's assume
// that it returns a JSON file with some basic content. We then create a
// new element, count all characters from some fictional content
// and insert it somewhere in your UI.
fetch('https://api.somewebsite.io/post/61454e0126ebb8a2e85d', { method: 'GET' })
  .then(response => {
    if (response.status === 200) {
      return response.json();
    }
  })
  .then(json => {
    if (json) {
      Object.keys(json).forEach(key => {
        const item = json[key];
        const count = item.content.trim().replace(/\s+/gi, '').length;
        const el = `
          <div class="foo-${item.className}">
            <p>Total characters: ${count}</p>
          </div>
        `;
        const wrapper = document.querySelector('.info-element');

        wrapper.innerHTML = el;
      });
    }
  })
  .catch(error => console.error(error));

Это не очень модульно. Все тесно связано и зависит от других частей. Представьте это с помощью более крупных и сложных функций, и вам придется отлаживать это, потому что что-то ломается. Может быть, API не отвечает, что-то изменилось внутри JSON или что-то еще. Кошмар, не правда ли?

Давайте выделим различные обязанности:

 // In the previous example we had a function that counted
// the characters of a string. Let's turn that into a module.
function countCharacters (text) {
  const removeWhitespace = /\s+/gi;
  return text.trim().replace(removeWhitespace, '').length;
}

// The part where we had a string with some markup in it,
// is also a proper module now. We use the DOM API to create
// the HTML, instead of inserting it with a string.
function createWrapperElement (cssClass, content) {
  const className = cssClass || 'default';
  const wrapperElement = document.createElement('div');
  const textElement = document.createElement('p');
  const textNode = document.createTextNode(`Total characters: ${content}`);

  wrapperElement.classList.add(className);
  textElement.appendChild(textNode);
  wrapperElement.appendChild(textElement);

  return wrapperElement;
}

// The anonymous function from the .forEach() method,
// should also be its own module.
function appendCharacterCount (config) {
  const wordCount = countCharacters(config.content);
  const wrapperElement = createWrapperElement(config.className, wordCount);
  const infoElement = document.querySelector('.info-element');

  infoElement.appendChild(wrapperElement);
}

Хорошо, теперь у нас есть три новых модуля. Давайте посмотрим на рефакторированный вызов fetch

 fetch('https://api.somewebsite.io/post/61454e0126ebb8a2e85d', { method: 'GET' })
  .then(response => {
    if (response.status === 200) {
      return response.json();
    }
  })
  .then(json => {
    if (json) {
      Object.keys(json).forEach(key => appendCharacterCount(json[key]))
    }
  })
  .catch(error => console.error(error));

Мы могли бы также взять логику из методов .then()

Если !modularization

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

Документируйте свой код

Документация является широко обсуждаемой темой. Одна часть сообщества программистов выступает за документирование всего, в то время как другая группа считает, что самодокументированный код — это путь. Как и с большинством вещей в жизни, я думаю, что хороший баланс делает код читаемым и масштабируемым. Используйте JSDoc для вашей документации.

JSDoc — это генератор документации API для JavaScript. Обычно он доступен как плагин для всех известных редакторов и IDE. Давайте рассмотрим пример:

 function properties (name, obj = {}) {
  if (!name) return;
  const arr = [];

  Object.keys(obj).forEach(key => {
    if (arr.indexOf(obj[key][name]) <= -1) {
      arr.push(obj[key][name]);
    }
  });

  return arr;
}

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

 /**
 * Iterates over an object, pushes all properties matching 'name' into
 * a new array, but only once per occurance.
 * @param  {String}  propertyName - Name of the property you want
 * @param  {Object}  obj          - The object you want to iterate over
 * @return {Array}
 */
function getArrayOfProperties (propertyName, obj = {}) {
  if (!propertyName) return;
  const properties = [];
  Object.keys(obj).forEach(child => {
    if (properties.indexOf(obj[child][propertyName]) <= -1) {
      properties.push(obj[child][propertyName]);
    }
  });
  return properties;
}

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

Организовать рабочий процесс коммитов

Рефакторинг — огромная миссия сама по себе. Чтобы всегда иметь возможность откатить ваши изменения (в случае, если вы что-то сломаете и заметите только позже), я рекомендую фиксировать каждое сделанное вами обновление. Переписал метод? git commitsvn commit Переименовали пространство имен, папку или несколько изображений? git commit Вы поняли идею. Это может быть утомительно для некоторых людей, но это действительно помогает вам правильно вымыться и собраться.

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

В случае, если вам нужно кратко обновить, как все это работает, есть интересное руководство от GitHub по их рабочему процессу контроля версий.

Как не сойти с ума

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

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

Всегда есть причины, почему код написан так, как он есть. Может быть, предыдущий разработчик просто не имел достаточно времени, чтобы сделать это должным образом, не знал лучше или что-то еще. Мы все были там.

Завершение

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

1. Проанализируйте проект

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

1. Создать базовый уровень

• .editorconfig чтобы обеспечить согласованность руководств по стилю кодирования между различными IDE.
• Сделайте отступы последовательными; табуляции или пробелы, не имеет значения.
• Обеспечить соблюдение правил именования.
• Если его еще нет, добавьте линтер , такой как ESLint , JSLint или JSHint .
• Обновите зависимости, но делайте это с умом и следите за тем, что именно было обновлено.

1. Убираться

• Создайте модульные тесты и автоматизируйте браузер с помощью таких инструментов, как Karma , Jasmine или Nightwatch.js .
• Убедитесь, что архитектура и шаблон дизайна соответствуют друг другу.
• Не смешивайте шаблоны дизайна , придерживайтесь уже существующих.
• Решите, хотите ли вы разбить свою кодовую базу на модули. Каждый должен иметь только одну цель и не знать об остальной логике вашей кодовой базы.
• Если вы не хотите этого делать, сосредоточьтесь больше на тестируемом коде и разбейте его на более простые блоки.
• Документируйте свои функции и код в сбалансированном виде с правильно названными функциями.
• Используйте JSDoc для создания документации для вашего JavaScript.
• Совершайте регулярно и после важных изменений. Если что-то сломается, проще вернуться.

1. Не сходи с ума

• Не сердитесь на предыдущего разработчика; негативность приведет только к ненужному рефакторингу и потере времени.
• Были причины, по которым код пишется так, как он есть. Имейте в виду, что мы все были там.

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