js.md

Оформление javascript кода

Часть правил оформления будет проверена автоматически,
на остальные обратят внимание менторы во время ручной проверки.

Ознакомиться с механизмом вы можете на демонстрационной задаче:
https://github.com/urfu-2016/demo-task-1

Правила для автоматической проверки

Когда вы отправляет пулл-реквест, ваш код автоматически проходит проверку
на соответствие этим правилам при помощи специального анализатора кода – eslint.

В случае, если проверка не прошла внизу пулла вы увидите:

Обратите внимание на ссылку «details», перейдя по ней, вы сможет найти ошибки:

ESlint подскажет в каких файлах и на какой строке произошла ошибка,
а так же какое именно правило было нарушено. В данном примере «no-unused-var».

Весь список правил можно изучить по ссылке: http://eslint.org/docs/rules

Если код удволетворяет всем правилам, вы увидите:

Вы можете не ждать автоматической проверки и всегда проверить код вручную,
выполнив локально команду npm i && npm run lint

Не пишите код впрок

Следуйте приниципу YAGNI (You ain't gonna need it) – не пишите код, который не понадобится вам для решения задачи. Если все проверки и тесты пройдены, значит кода уже достаточно – потратьте время на рефакторинг.

Плохо:

// My awesome math utils
function sum(numbers) {}
function average(numbers) {}
function median(numbers) {}

sum([1, 2, 3]);
// 6

Хорошо:

function sum(numbers) {}

sum([1, 2, 3]);
// 6

Не повторяйтесь

Следуйте приниципу DRY (Don’t repeat yourself) – не пишите похожий код несколько раз,
старайтесь его переиспользовать.

Плохо:

var averageRating = ratings
    .reduce(function (sum, rating) {
        return sum + rating;
    }, 0) / ratings.length;

var averageGrade = grades
    .reduce(function (sum, grade) {
        return sum + grade;
    }, 0) / grades.length;

Хорошо:

function getAverageOf(numbers) {}

var averageRating = getAverageOf(ratings);
var averageGrade = getAverageOf(grades);

Пишите проще

Следуйте приниципу KISS (Keep it short and simple) – пишите проще
и по полной используйте все возможности языка.

Плохо:

var numbers = [1, 4, 5, 2, 3];

// Сортируем числа
// TODO: оптимизировать – может быть быструю сортировку?
for (var i = 0; i < numbers.length; i++) {
    for (var j = 0; j < numbers.length; j++) {
        if (numbers[j] > numbers[j+1]) {
            var greatest = numbers[j];

            numbers[j] = numbers[j+1];
            numbers[j+1] = greatest;
        }
    }   
}

Хорошо:

var numbers = [1, 4, 5, 2, 3];

numbers.sort()

Называйте переменные понятно

1. Используйте camelCase

Плохо:

var apples_count = 5;
var Language = 'ru';

Хорошо:

var applesCount = 5;
var language = 'ru';

2. Для объявления констант используйте заглавные буквы, разделённые _:

Плохо:

var currentYear = new Date().getFullYear();

Хорошо:

var CURRENT_YEAR = new Date().getFullYear();

3. Используйте только английские слова, не используйте транслит

Плохо:

var ssilka = 'http://esling.org/';
var ссылка = 'http://esling.org/';

Хорошо:

var link = 'http://esling.org/';

4. Вкладывайте смысл в название – оно должно быть однозначным и понятным

Плохо:

var a, b; // Не несут смысла
var list; // Слишком абстрактно – список чего?

Хорошо:

var overallPrice, publishDate;
var grocceryList;

Допустимо использовать i, j в качестве итераторв цикла for (var i = 0; i < 2; i++) {},
и a, b – в функциях сортировки grocceryList.sort(function (a, b) {})

5. Логические перменные начинайте с модальных глаголов

Плохо:

var accessToPublish
var visible;

Хорошо:

var canPublish
var isVisible;

6. Не используйте сокращения и не пишите избыточные имена

Плохо:

var btn;
var dateOfFirstPublication;
var postsCollection;

Хорошо:

var button;
var publishDate;
var posts;

7. Объявляйте переменные максимально близко к месту использования

Плохо:

var hasAccess = hasAccess(); // Далеко от места использования
var comments = getComments();
var overalRaiting = 0;

for (var i = 0; i < comments.length; i++) {
    overallRating += comments[i].rating;
}

if (hasAccess) {
    show(overallRating);
}

Хорошо:

var comments = getComments();
var overalRaiting = 0;

for (var i = 0; i < comments.length; i++) {
    overallRating += comments[i].rating;
}

var hasAccess = hasAccess();
if (hasAccess) {
    show(overallRating);
}

8. Для именования функций используйте глаголы

Плохо:

function length() {}
function title(name) {}
function visible() {}

Хорошо:

function getLength() {}
function setTitle(name) {}
function isVisible() {}