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

JavaScript, the winning style

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

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

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

• Google JavaScript Style Guide
• npm’s coding style
• Felix’s Node.js Style Guide
• Idiomatic JavaScript
• jQuery JavaScript Style Guide
• Douglas Crockford’s JavaScript coding style

Помимо гайдов, не стоит так же забывать об автоматических анализаторах кода, таких, например, как 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.

  Перевод:

  Глобальные переменные сложнее отлаживать, и они могут стать причиный нетривиальных проблем, когда двум проектам надо интегрироваться. Да бы совместить весь общий код на JavaScript, мы составили соглашение, чтобы предотвратить возможные противоречия.
• 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): 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

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

• Используйте как в примере: 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)

Автор: 505abc

Источник