Статьи

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

Эта статья была рецензирована Томом Греко , Диви Толией и Раби Кираном . Спасибо всем рецензентам SitePoint за то, что сделали контент SitePoint как можно лучше!

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

Почему руководства по стилю

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

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

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

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

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

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

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

Для JavaScript существует ряд общих и специфических для проекта руководств по стилю:

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

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

Проекты AngularJS нуждаются в руководстве по стилю в значительной степени по той же самой причине, что все проекты JavaScript нуждаются в руководстве по стилю, но есть некоторые специфичные для Angular элементы, которые можно охватить.

Давайте рассмотрим следующие примеры AngularJS:

  • Как использовать нг теги . Директивы AngularJS ng могут использоваться по-разному и иметь разный синтаксис, например, предпочитая data-ng вместо ng при использовании директивы ng в качестве атрибута HTML, чтобы быть W3C-совместимым. Указание того, как писать директивы ng в руководстве по стилю кода, помогает улучшить согласованность файлов HTML.

  • Различные способы реализации компонентов . AngularJS реализует веб-компоненты с использованием пользовательских директив. Пользовательские директивы могут основываться на именах элементов HTML, атрибутах, именах классов, а также комментариях. Руководство по стилю может гарантировать, что, например, в проекте используется только один тип директивы.

  • Какой архитектурный образец принять . AngularJS позволяет использовать архитектурные шаблоны MV * (или MVW). Таким образом, разработчики JavaScript могут выбирать, реализовывать ли их приложение на основе MVC или MVVM. Указания о том, какой подход должен использоваться в проекте, помогают удерживать всю команду на одном пути.

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

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

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

Трудно сказать, какой из них лучший, так как они все хорошие гиды по стилю. Руководство Джона Папы является всеобъемлющим и развивающимся, руководство Тодда Мотто лаконичным и отличным для начала, а руководство Минько Гечева переведено на разные языки. Но похоже, что руководство по стилю Джона Папы было официально рекомендовано как самое актуальное и подробное руководство по стилю AngularJS.

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

  • Принцип ЛИФТА
  • Контроллер как синтаксис
  • Fle шаблоны и фрагменты
  • Семенные аппликации

Принцип ЛИФТА

Принцип LIFT связан со структурой приложения и определяет следующие рекомендации:

  1. Быстро найдите свой код
  2. Я сглаживаю код с первого взгляда
  3. сохранить структуру F lattest вы можете
  4. Пробуйте остаться сухим

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

ControllerAs

Использование синтаксиса controllerAs поверх синтаксиса «classic controller with $scope

 <!-- avoid -->
<div ng-controller="CustomerController">
    {{ name }}
</div>

<!-- recommended -->
<div ng-controller="CustomerController as customer">
    {{ customer.name }}
</div>

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

 /* avoid */
function CustomerController($scope) {
    $scope.name = {};
    $scope.sendMessage = function() { };
}

/* better */
function CustomerController() {
    this.name = {};
    this.sendMessage = function() { };
}

На самом деле, рекомендуется пойти дальше и назначить this

 /* recommended */
function CustomerController() {
    var customerVM = this;
    customerVM.name = {};
    customerVM.sendMessage = function() {
        // we can access the controller's scope as customerVM
    };
}

Шаблоны файлов и фрагменты

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

Семенные Приложения

Если вы спешите или хотите учиться на полном примере, HotTowel – это вариант, который следует учитывать при запуске новых проектов AngularJS. Этот генератор Yeoman создает приложение, которое служит отправной точкой для вашего приложения AngularJS, следуя руководству по стилю Джона Папы. Сгенерированное приложение настраивается с помощью пакета npm, файла gulp, подсказок JavaScript и LESS, поэтому, если у вас нет особых потребностей, все, что вам нужно сделать, это реализовать новые функции! Вы можете просматривать и запускать приложение AngularJS, созданное с помощью HotTowel, на моей игровой площадке AngularJS на GitHub.

Пример из реального мира

Примером руководства по стилю, используемого для реального проекта, является стилегид GoCardless AngularJS , в котором вы можете найти более конкретные и продвинутые фрагменты кода. Это продвигает использование директив вместо контроллеров в HTML. В качестве примера рассмотрим это руководство по именам директив:

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

 <!-- Recommended -->
<dialog-box></dialog-box>
<button click-toggle="isActive"></button>

<!-- Avoid -->
<dialog></dialog>
<button toggle="isActive"></button>

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

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

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

Будущее: 2016 и далее

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

Мне бы хотелось услышать об опыте других людей в руководствах по стилю, как для Angular, так и для JavaScript в целом. Есть ли какие-то замечательные руководства, которые я пропустил, или какие-либо рекомендации, которые вы считаете особенно спорными? Дай мне знать в комментариях!