Важность написания кода, который могут прочитать люди

 // This may be most performant
$el[0].checked;

// But these are still fast, and are much easier to read
// Source: http://jsperf.com/prop-vs-ischecked/5
$el.prop('checked');
$el.is(':checked');
$el.attr('checked');

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

Non-Code

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

Пробелы

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

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

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

 function sendPostRequest(url, data, cb) {
    // A few assignments grouped together and neatly indented
    var requestMethod = 'POST',
        requestHeaders = {
            'Content-Type': 'text/plain'
        };

    // XMLHttpRequest initialisation, configuration and submission
    var request = new XMLHttpRequest();
    request.addEventListener('load', cb, false);
    request.open(requestMethod, url, false);
    request.send(data);
}

Комментарии

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

• объяснение и аргументация неочевидного кода ,

• какую ошибку или причуду исправляет исправление, и источники, когда они доступны.

 // Sum values for the graph’s range
var sum = values.reduce(function(previousValue, currentValue) { 
    return previousValue + currentValue;
});

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

 if ('addEventListener' in element) {
    element.addEventListener('click', myFunc);
}
// IE8 and lower do not support .addEventListener, 
// so .attachEvent should be used instead
// http://caniuse.com/#search=addEventListener
// https://msdn.microsoft.com/en-us/library/ms536343%28VS.85%29.aspx
else {
    element.attachEvent('click', myFunc);
}

Встроенная документация

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

 /**
 * Create a HTTP request
 * @constructor
 * @param {string} url
 */
function HttpRequest(url) {
    // ...
}

/**
 * Set an object of headers
 * @param {Object} headers
 * @return {HttpRequest}
 */
HttpRequest.prototype.setHeaders = function(headers) {
    for (var header in headers) {
        this.headers[header] = headers[header];
    }

    // Return self for chaining
    return this;
};

Головоломки обратного вызова

События и асинхронные вызовы являются отличными функциями JavaScript, но они часто затрудняют чтение кода.

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

 function doRequest(url, success, error) { /* ... */ }

doRequest('https://example.com/api/users', function(users) {
    doRequest('https://example.com/api/posts', function(posts) {
        // Do something with users and posts
    }, function(error) {
        // /api/posts went wrong
    });
}, function(error) {
    // /api/users went wrong
});

Объект Promise Это позволяет сгладить вложенные асинхронные запросы.

 function doRequest(url) {
    return new Promise(function(resolve, reject) {
        // Initialise request
        // Call resolve(response) on success
        // Call reject(error) on error
    });
}

// Request users first
doRequest('https://example.com/api/users')
// .then() is executed when they all executed successfully
.then(function(users) { /* ... */ })
// .catch() is executed when any of the promises fired the reject() function
.catch(function(error) { /* ... */ });

// Run multiple promises parallel
Promise.all([
    doRequest('https://example.com/api/users'),
    doRequest('https://example.com/api/posts')
])
.then(function(responses) { /* ... */ })
.catch(function(error) { /* ... */ });

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

ES6 / ES2015

Если вам известна спецификация ES2015, возможно, вы заметили, что все примеры кода в этой статье относятся к более старым версиям (за исключением объекта Promise Несмотря на то, что ES6 предоставляет нам отличные возможности, есть некоторые проблемы с удобочитаемостью.

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

 var add = (a, b) => a + b;
console.log(add(1, 2)); // 3

Другой пример — синтаксис отдыха и распространения.

 /**
 * Sums a list of numbers
 * @param {Array} numbers
 * @return {Number}
 */
function add(...numbers) {
    return n.reduce(function(previousValue, currentValue) {
        return previousValue + currentValue;
    }, 0);
}

add(...[1, 2, 3]);

/**
 * Sums a, b and c
 * @param {Number} a
 * @param {Number} b
 * @param {Number} c
 * @return {Number}
 */
function add(a, b, c) {
    return a + b + c;
}

add(1, 2, 3);

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

Вывод

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

• JSHint — JavaScript-линтер, чтобы сохранить код без ошибок
• Idiomatic — популярный стандарт стиля кода, но не стесняйтесь отклоняться
• EditorConfig — определение стилей кода кросс-редактора

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

Что вы думаете о написании читаемого и поддерживаемого кода? Я хотел бы услышать их в комментариях ниже.