Что такое руководство по стилю? Нужны ли проектам, создаваемым на AngularJS подобные руководства? Как бы вы могли использовать это в командной разработке? На эти и подобные вопросы будет дан подробный ответ в сегодняшней статье.

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

Необходимость в руководстве по стилю

Википедия дает хорошее определение для понимания, зачем нужны подобные руководства в общем:

Стиль руководства (или руководство стиля) — это набор стандартов для написания и оформления документов, либо для общего использования или для конкретной публикации, организации, или сферы деятельности. (Его часто называют таблицей стилей, хотя этот термин имеет и другие значения.)

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

Руководства по стилю реализуют в жизнь лучшие практики по написанию кода в соответствии с определенным языком программирования и нуждами вашей команды или организации.

Руководства по стилю кода в JavaScript проекте

Существует некоторое количество объективных причин, почему проекты на JavaScript нуждаются в подобных руководствах. В этой статье не рассмотрены абсолютно все причины, но, если вкратце, на основе следующих тем создаются основные принципы стиля кода:

1. Модульность: одиночная ответственность, немедленно вызываемые функциональные выражения ( IIFE ), зависимости модулей
2. Структура приложения: архитектурные паттерны, структура директорий
3. Соглашение в именах для модулей, контроллеров, конфигураций
4. Проверка JavaScript кода
5. Тестирование
6. Комментирование кода и создание документации
7. Логика запуска и конфигурирования приложения
8. Роутинг и навигация
9. Обработка ошибок
10. Производительность и безопасность – минификация, обфускация и т.п.

Существующие JavaScript руководства по стилю

Для JavaScript существует множество руководств по стилю кода, в которых рассматривается общее применение определенных правил и соглашений или конкретное применение к определенным случаям, или проектам.

Далее приведены несколько ссылок на подобные руководства:

• Google JavaScript Guide
• Mozilla coding style
• Crockford’s code conventions
• Waldron’s Principles of Writing Consistent, Idiomatic JavaScript
• npm’s “funny” coding style
• jQuery’s JavaScript Style Guide
• Airbnb JavaScript style guide

Несмотря на известные имена в названиях, ни одно из этих руководств не является всеобъемлющем. Хотя, в первую очередь, стоит обратить внимание на руководство от Airbnb, которое является наиболее полным и современным, а также предоставляет eslint конфигурацию для проверки соответствия написанного кода руководству по стилю.

Почему AngularJS проекты нуждаются в руководстве по стилю

AngularJS проекты нуждаются в руководстве по стилю кода во многом по тем же причинам, что и остальные проекты на JavaScript и о которых было написано выше. Но существуют определенные причины, специфичные именно для AngularJS проектов.

Рассмотрим несколько примеров, относительно AngularJS:

• Использование ng-тегов. AngularJS ng-директивы могут быть использованы различными способами и имеют неодинаковый синтаксис. Например, использование data-ng вместо ng в качестве HTML атрибута директивы ng, будет необходимым для валидации HTML кода по правилам W3C. Следование определенному стилю при написании ng-директив, послужит улучшению логичности и согласованности в HTML-файлах.
• Различные способы реализации компонентов. AngularJS реализует web-компоненты используя кастомные директивы. Такие директивы могут быть созданы на основе имен HTML элементов, атрибутах, имен классов, а также на основе комментариев. Руководстве по стилю поможет определиться с тем, какой именно вариант создания директив в проекте будет использован.
• Применение определенного архитектурного паттерна. AngularJS следует MV* ( или Модель-Вид-Что-угодно ) архитектурному паттерну, что предоставляет возможность разработчику реализовать свое приложение на основе MVC или MVVC паттерна. Рекомендации в руководстве также помогут определиться с выбором необходимого паттерна, что позволит всей команде разработчиков проекта придерживаться основной линии создания приложения.

Теперь, когда у нас есть понимание для чего нужно руководство по стилю, мы готовы погрузиться в существующие AngularJS руководства.

AngularJS руководства по стилю кода

Создатель AngularJS – компания Google, предоставляет официальное руководство по стилю и лучшие практики по написанию кода.

Но самыми популярными и всеобъемлющими являются руководства от AngularJS сообщества:

• Minko Gechev’s AngularJS Style Guide
• Todd Motto’s AngularJS Style Guide
• John Papa’s AngularJS Style Guide

Сложно сказать, которое из них лучшее. Руководство от John Papa довольно таки исчерпывающее само по себе и постоянно развивается. От Todd Motto кратко и лаконично, и хорошо для быстрого старта. Ну, а руководство от Minko Gechev переведено на множество языков, в том числе на русский.

Но, скорей всего, лучшим выбором будет вариант от John Papa, так как именно его руководство было официально рекомендовано как наиболее современное и детальное.

Поэтому, рассмотрим несколько из наиболее важных рекомендаций в руководстве от John Papa, которым стоит придерживаться при начинании нового AngularJS проекта:

• Принципы LIFT, которые мы разберем немного позже
• controllerAs синтаксис
• Сниппеты и шаблоны файлов
• Стартовое приложение

LIFT принципы при создании AngularJS приложения

Данные принципы, используемые при создании приложения, относятся к его структуре, а именно:

1. Создавайте структуру вашего приложения, которая будет интуитивно понятна, проста и в ней можно будет быстро ориентироваться
2. Когда вы смотрите на файл, вы должны немедленно понимать, что он содержит и за что отвечает
3. Сохраняйте плоской структуру директорий насколько это возможно. Когда у вас появляется от семи файлов и более, тогда начните рассматривать возможность их разделения
4. Не повторяйте свой код. Но без фанатизма и без ущерба читаемости

Все это способствует созданию расширяемой структуры и более эффективной разработки приложения из-за быстрого поиска и нахождения нужного кода. Также используйте имя директории, описывающее особенность работы содержащегося в ней кода.

controllerAs синтаксис

Использование controllerAs синтаксиса вместо обычного контроллера с $scope синтаксисом, поможет улучшить читаемость кода:

<!--  Обычные синтаксис  -->
<div ng-controller="MyController">
  {{ title }}
</div>

<!-- Рекомендованный  -->
<div ng-controller="MyController as book">
  {{ book.title }}
</div>

И в контроллере:

/* Обычные синтаксис */
function MyController( $scope )
{
  $scope.title = {};
  $scope.doSomething = function() {};
}

/* Лучший вариант */
function MyController ()
{
  this.title = {};
  this.doSomething = function() {};
}

Более того, рекомендуется присваивать переменной значение this для доступа к нему в методах вашего контроллера:

/* Рекомендовано */
function MyController() 
{
  var vm = this;
  vm.title = {};
  
  vm.doSomething = function()
  {
    /* Здесь, у нас есть доступ к области контроллера через vm */
  };
}

Сниппеты и шаблоны файлов

В руководстве от John Papa есть несколько шаблонов и сниппетов для различных редакторов и IDE.

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

Стартовое приложение

Если вы хотите изучить пример стартового приложения для создания нового AngularJS проекта, будет хорошей идеей рассмотреть HotTowel. Это Yeoman генератор, который создаст стартовый шаблон в качестве начальной точки вашего AngularJS приложения в соответствии с руководством по стилю от John Papa.

Созданное приложение конфигурируется с помощью npm, gulp, JavaScript и Less сниппетов – таким образом, если у вас нет особых требований к приложению, тогда можно приступить к реализации функционала сразу же после генерации стартового шаблона.

Практический пример использования руководства по стилю

Хорошим примером использования руководства по стилю может послужить проект GoCardless и его рекомендации AngularJS Style guide, в которых можно найти более определенные и продвинутые примеры кода. В данном руководстве, например, рекомендуется использовать директивы в HTML, вместо контроллеров. Также, там можно найти замечания по поводу именования директив:

Имена директив должны содержать только символы a-z и по крайней мере одно тире ( - ). Почему: Создаваемые элементы должны содержать тире ( для создания пространства имен ), чтобы отличать их от нативных AngularJS элементов и предотвратить тем самым возможные коллизии компонентов.

<!--  Рекомендовано  -->
<dialog-box></dialog-box>
<button click-toggle="isActive"></button>

<!--  Следует избегать  -->
<dialog></dialog>
<button toggle="isActive"></button>

Руководство от GoCardless послужит отличной стартовой точкой для дальнейшей кастомизации и расширения данных стилей в соответствии с потребностями вашей команды и проекта.

Использование руководства по стилю в командной разработке

Руководство по стилю кода должно стать необходимым элементом для большинства AngularJS проектов, особенно, если проект ожидает большой рост или над ним начинает работу новая команда разработчиков. Также, руководство по стилю должно поддерживаться в актуальном состоянии в течении жизни проекта, изменяться и расширяться каждый раз, когда появляется новая потребность.

На этом введение в AngularJS руководство по стилю кода завершено. Следующим важным изменением в руководстве будет обновление для AngularJS 2, особенно в условиях разработки с использованием web-компонентов, ECMAScript 2015 (ES6), ECMAScript 2016 и подобных современных инструментов.