15 August 2013

Оформление кода, оптимизация процесса проверки качества кода

Website developmentJavaScriptPerfect code
Translation
Original author: Otto Kekäläinen

JavaScript, the winning style



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

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

В отличие от Питона у которого есть единый свод правил «Style Guide for Python Code», у языка JavaScript такого нет. Однако на выбор есть целых 6 популярных гайдов:



Помимо гайдов, не стоит так же забывать об автоматических анализаторах кода, таких, например, как JSLint и JSHint. И в них уже заложены свои настройки. Вопрос в том, какой же все-таки максимально правильный способ писать код на JavaScript, который был бы актуален и максимально соответствовал бы большинству рекомендаций? Давайте попробуем объединить большинство рекомендаций в этой статье и подумаем как можно оптимизировать процесс проверки качества кода.

Оформление


Отступ

  • 2 пробела, не больше и без табуляции: Google, npm, Node.js, Idiomatic
  • Табуляция: jQuery
  • 4 пробела: Crockford


Пробел между аргументами и выражением

  • Без пробела, как на примере: Google, npm, Node.js

    project.MyClass = function(arg1, arg2) {
    

  • С пробелом, как на примере: Idiomatic, jQuery

    for ( i = 0; i < length; i++ ) {
    

  • Без особого мнения: Crockford


Многие гайды так же напоминают, чтобы не было пробелов в конце строк (trailing spaces)

Длина строки

  • Максимум 80 знаков: Google, npm, Node.js, Crockford

    При переносе строк, отступ не обязательно должен быть равен 2, если вам надо, например, перенести на следующую строку аргументы функции, то выровнить их можно по тому месте где стоит первый аргумент. Как другой вариант, можно так же использовать 4 пробела вместо 2, когда переносите длинные строки.

  • Без особого мнения: jQuery, Idiomatic


Точка с запятой

  • Всегда использовать точку с запятой: Google, Node.js, Crockford
  • Не использовать в некоторых ситуациях: npm
  • Без особого мнения: jQuery, Idiomatic


Комментарии:

  • JSDoc: Google, Idiomatic
  • В Idiomatic Style Guide так же разрешены более простые комментарии, но JSDoc предпочтительнее
  • Без особого мнения: npm, Node.js, jQuery, Crockford


Кавычки

  • Предпочтительнее одинарные кавычки. Лучше 'value', чем "value": Google, Node.js
  • Двойные кавычки ": jQuery
  • Без особого мнения: npm, Idiomatic, Crockford


Декларирование переменных

  • Одна переменная на одной строке: Node.js

    var foo = '';
    var bar = '';
    

  • Несколько переменных, разделяемые запятыми в конце строки, как на примере: Idiomatic, jQuery

    var foo = "",
       bar = "",
       quux;
    

  • Запятая в начале строки: npm

    var foo = ""
      , bar = ""
      , quux;
    

  • Без особого мнения: Google, Crockford


Скобки

  • Ставьте открывающую скобки на той же строке: Google, npm, Node, Idiomatic, jQuery, Crockford

    function thisIsBlock() {
    

    Это подразумевает, что скобки следует использовать всегда, даже в ситуации, где их можно опустить.

  • В npm гайде указано, что скобки нужно использовать только в случае, когда тело функции переносится на следующую строку.

    if (foo) bar()
    while (foo) {
      bar()
    }
    


Глобальные переменные

  • Не используйте глобальные переменные: Google, Crockford

    Google:
    Global name conflicts are difficult to debug, and can cause intractable problems when two projects try to integrate. In order to make it possible to share common JavaScript code, we’ve adopted conventions to prevent collisions.

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


  • Crockford считает, что глобальные переменные не нужно использовать вовсе.
  • Без особого мнения: Idiomatic, jQuery, npm, Node


Имена



Переменные

  • Первое слово с маленькой буквы, все последующие с большой: Google, npm, Node, Idiomatic

    var foo = "";
    var fooName = "";
    


Константы


  • Все слово большими буквами: Google, npm, Node

    var CONS = 'VALUE';
    var CONSTANT_NAME = 'VALUE';
    

  • Без особого мнения: jQuery, Idiomatic, Crockford


Функции

  • Первое слово с маленькой буквы, все последующие с большой (camelCaps/camelCase): Google, npm, Node, Idiomatic

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

    function veryLongOperationName
    function short()..
    


    Используйте слова is, set, get:

    function isReady()
    function setName()
    function getName()
    

  • Без особого мнения: jQuery, Crockford


Массивы

  • Используйте множественную форму слова: Idiomatic

     var documents = [];
    

  • Без особого мнения:Google, jQuery, npm, Node, Crockford


Объекты и классы

  • Используйте Pascal case (каждое слово с большой буквы): Google, npm, Node

    var ThisIsObject = new Date();
    

  • Без особого мнения: jQuery, Idiomatic, Crockford


Другое

Используйте all-lower-hyphen-css-case для многосоставных названий файлов и настроек: npm

Используйте JSHint и .jshintrc файл


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

{
  "camelcase" : true,
  "indent": 2,
  "undef": true,
  "quotmark": "single",
  "maxlen": 80,
  "trailing": true,
  "curly": true
}


Во все файлы, которые обрабатываются браузером добавляем:

/* jshint browser:true, jquery:true */


В файлы Node.js добавляем:

/*jshint node:true */


Во все типы JS файлов, так же лучше добавить:

'use strict';


Это повлияет и на JSHint и на обработчика JavaScript в целом, который станет менее терпимым к ошибкам, но будет работать быстрее. Почитать больше о 'use strict' (внешняя ссылка)

Автоматическая проверка кода JSHint перед git commit


Если вы хотите быть уверены в том что все ваши JS файлы прошли проверку и следуют общему стилю, который вы определили в .jshintrc. То добавьте эти строки в ваш .git/hooks/pre-commit файл. Теперь перед тем как закомитить изменения, скрипт будет проверять только измененные файлы на нарушения стилистики кода. И если таковые имеются, то операция будет прервана.

#!/bin/bash
# Pre-commit Git hook to run JSHint on JavaScript files.
#
# If you absolutely must commit without testing,
# use: git commit --no-verify

filenames=($(git diff --cached --name-only HEAD))

which jshint &> /dev/null
if [ $? -ne 0 ];
then
  echo "error: jshint not found"
  echo "install with: sudo npm install -g jshint"
  exit 1
fi

for i in "${filenames[@]}"
do
	if [[ $i =~ \.js$ ]];
	then
		echo jshint $i
		jshint $i
		if [ $? -ne 0 ];
		then
			exit 1
		fi
	fi
done


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

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

Оригинальная статья: (http://seravo.fi/2013/javascript-the-winning-style)
Tags:javascriptjslintjshintjquerygitpre-commit hookstyleguidesnode.jsnodenodejsпереводgoogleguidesоформление кода
Hubs: Website development JavaScript Perfect code
+49
34.3k 491
Comments 61
Popular right now
Top of the last 24 hours