js-codestyle.md

Требования к оформлению JavaScript

Ниже приведен список правил, на которые мы обращаем внимание при приеме домашних заданий.

Переменные

1. Имена переменных пишутся в camelCase, имена констант - заглавными буквами, разделяя подчеркиваниями.

Плохо:

var students_count;         // В качестве разделителя используется `_`
var Language;               // Первая буква - прописная

Хорошо:

var studentsCount;
var language;
var MILLISECONDS_IN_DAY;    // Если это константа

2. Для именования переменных использовать только английские слова, не использовать транслит.

Плохо:

var cena;
var ssilka;
var процент;

Хорошо:

var price;
var link;
var percent;

3. Название переменной должно нести смысл, быть однозначным и понятным, отражать хранимое значение.

Плохо:

var a, b, c;    // Из названия непонятно, для чего нужны эти переменные
var array;      // Слишком общее название, непонятно, к чему относится
var visible;    // Непонятно, данные какого типа хранятся в переменной

Хорошо:

var beginDate, endDate;
var posts;
var isVisible;

В качестве итераторов цикла допустимо использовать i, j, ...

4. Старайтесь не использовать сокращения в переменных. Но и не пишите слишком длинные имена.

Плохо:

var idx;
var btn;
var dateOfFirstPublicationForCurrentPost;

Хорошо:

var index;
var button;
var publishDate;

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

Плохо:

var canPublish = ...;    // Далеко от места использования
var comments = ...;
var overalRaiting = 0;

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

if (canPublish) { ... }

Хорошо:

var comments = ...;
var overalRaiting = 0;

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

var canPublish = ...;    // Максимально близко к месту использования

if (canPublish) { ... }

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

Плохо:

function length() { ... }
function title(name) { ... }
function publish() { ... }

Хорошо:

function getLength() { ... }
function setTitle(name) { ... }
function canPublish() { ... }

Кодстайл

Для проверки кодстайла используем утилиту JSCS. Чтобы запустить её на вашем компьютере необходимо:

1. Клонировать репозиторий с домашним заданием (инструкция по работе с GitHub).
2. Зайти в консоли в папку с клонированными файлами
3. Выполнить npm install для установки JSCS
4. Выполнить npm run lint каждый раз, когда хотим проверить кодстайл.

Если ваш код полностью удовлетворяет кодстайлу - вы увидите сообщение No code style errors found., иначе – список ошибок. Если что-то вам не понятно, всегда можно спросить ментора :)

Общие правила

1. Избегайте большой вложенности

Плохо:

function () {
    if (...) { // Первый уровень вложенности
        if (...) { // Второй уровень вложенности
            if (...) { // Третий уровень вложенности
                            // ...
                            if (...) { // Десятый уровень вложенности
                            }
            }
        }
    }
}

Старайтесь не использовать больше двух уровней вложенности

Хорошо:

function () {
    if (...) { // Первый уровень вложенности
        if (...) { // Второй уровень вложенности
        }
    }
}

2. Не передавайте в функцию слишком много аргументов:

Плохо:

function (title, annotation, body, publishDate, tags, author) {
    // ...
}

Старайтесь передавать не больше трех параметров

Хорошо:

function (postData, author, metaData) {
    // ...
}

3. Используйте строгий режим.

'use strict';     // Пишем вначале каждого файла

4. Если код кажется вам не очевидным - постарайтесь сделать его проще, лучше, читаемее. Если даже после рефакторинга остались неочевидные места - оставьте комментарий.

5. Не повторяйтесь. Не пишите похожий код несколько раз, старайтесь его переиспользовать.

Плохо:

console.log('Среднее: ' + (max + min) / 2);
// ...
console.log('Результат: ' + (max + min) / 2);

Хорошо:

var average = (max + min) / 2;

console.log('Среднее: ' + average);
// ...
console.log('Результат: ' + average);