Повторяющееся имя модуля для каждого компонента модуля

В известном сообщении в блоге Рекомендации по лучшей практике для структуры приложения Angular описана новая рекомендуемая структура проекта angularjs, которая теперь компонентно-ориентированный, а не функционально-ориентированный, или как указано в первоначальной проблеме github — «Организовано Особенность".

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

userlogin/
    userlogin.js
    userlogin.css                
    userlogin.html                
    userlogin-directive.js
    userlogin-directive_test.js
    userlogin-service.js
    userlogin-service_test.js 

Возникает вопрос: в чем смысл, плюсы и минусы повторения имени модуля внутри каждого имени файла в модуле по сравнению с функциональными именами файлов? Например:

userlogin/
    userlogin.js
    userlogin.css                
    userlogin.html   
    controllers.js             
    directives.js
    services.js

Причина, по которой я спрашиваю, заключается в том, что я пришел из мира Django, где существует несколько схожая идея иметь проекты и приложения. У каждого приложения обычно есть свои models.py, views.py, urls.py, tests.py. В именах сценариев нет повторяющегося имени приложения.

Я надеюсь, что я не перехожу черту, основанную на мнении, и есть законная причина для следования подходу.


person alecxe    schedule 28.07.2014    source источник
comment
Повторение имени компонента в имени файла очень полезно, когда в вашей среде IDE открыто несколько вкладок (файлов). В большинстве IDE заголовком вкладки является имя открытого файла. Просто взглянув на заголовок вкладки, вы можете сразу определить, какой компонент является файловой частью. Без повторения имени вы можете легко открыть несколько вкладок с одним и тем же заголовком, а навигация по проекту становится немного сложной и подверженной ошибкам.   -  person artur grzesiak    schedule 05.08.2014
comment
Я также являюсь пользователем Django + Angular и не добавляю имя модуля в имена файлов. Мое личное мнение, что это создает ощущение чистоты в проекте и помогает при повторном просмотре кода, над которым я некоторое время не работал.   -  person LGama    schedule 11.08.2014


Ответы (5)


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

«Обзорность» — это способность организации кодовой базы (структура папок, имена файлов, метаобъекты и т. д.) обеспечивать быстрый и информативный обзор реализованного программного обеспечения.

Значимость «обзорности» экспоненциально возрастает с увеличением размера кодовой базы и размера команды разработчиков, работающих над проектом*, по следующим причинам (неполный список):

  1. Когда кодовая база велика, вероятность того, что определенные части кода останутся нетронутыми в течение определенного периода времени, увеличивается (по мере увеличения продолжительности этого «холодного» периода).

  2. Когда новые участники присоединяются к команде, вы хотите, чтобы они как можно скорее были в курсе (и не разочаровывались в процессе). «Обзорность» помогает обеспечить хорошую высокоуровневую абстракцию всего проекта и обычно также дает хорошее представление о том, как все работает (чаще всего это создает ощущение знакомости; как будто вы видели кодовую базу раньше, хотя у вас нет).


"Итак, хорошо, "обзорность" важна. Вот почему у нас есть такая приятная, ориентированная на компоненты структура и т. д. Но зачем ставить перед каждым файлом имя компонента?"

Что ж, это может показаться забавным, но префикс всех имен файлов, связанных с компонентами, обеспечивает определенный порядок. Например. частичный HTML или CSS всегда будут отображаться перед контроллерами и т. д.:

...               
userlogin.html                
userlogin-controller.js
...

Там, где это не для префикса, вы получите разные порядки в зависимости от имени компонента. Например.:

...                       ...                      ...
controller.js             controller.js            bookself.html
...                       ...                      ...
service.js         VS     service.js        VS     controller.js
...                       ...                      ...
userlogin.html            zombi.html               service.js
...                       ...                      ...

Использование префикса гарантирует, что файлы отображаются в определенном порядке: контроллер всегда идет после части HTML, сервис также и т. д. Например:

...                             ...                         ...
userlogin.html                  zombi.html                  bookself.html
...                             ...                         ...
userlogin-controller.js    VS   zombi-controller.js    VS   bookself-controller.js
...                             ...                         ...
userlogin-service.js            zombi-service.js            bookself-service.js
...                             ...                         ...

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

т.е. контроллеры не находятся в файле с именем "‹component›-controllers.js".
Они находятся в первом файле, имя которого значительно длиннее, чем у предыдущих файлов.
Служба (если есть) находится в файле с меньшим именем в конце и т. д.

Испортите это (т.е. испортите порядок из-за начальной буквы или перепутаете их относительную длину из-за длинных/коротких имен компонентов), и вы сами окажетесь в ситуации, похожей на необходимость чтения чего-то с жесткого диска, вместо того, чтобы просто читать это из ОЗУ. (Ни один разработчик не хочет туда идти :))


*: На самом деле здесь важно то, что мы называем «потоком команды разработчиков», то есть как часто член команды будет уходить (например, чтобы работать над чем-то другим, покидать компанию и т. д.) или будет представлен новый член. .
Обычно, чем больше команда, тем сильнее поток.

person gkalpak    schedule 05.08.2014
comment
Вау, как-то не подумал об этом. Совершенно логично, большое спасибо! - person alecxe; 05.08.2014
comment
человеческий разум очень хорошо распознает визуальные образы -- очень хорошо сказано! - person Dave Alperovich; 06.08.2014
comment
На этот вопрос есть продолжение: Организация проекта и соглашения об именах - действительно ценю вашу проницательность. Спасибо. - person alecxe; 11.09.2014

tl;dr; Хотя другие ответы не являются неправильными по большинству пунктов, они не признают важность инструментов навигации по файлам, доступных сегодня для разработчиков.


Быстрая навигация по файлам проекта

Как только мы достаточно хорошо познакомимся с проектом, мы захотим перемещаться между файлами, не заглядывая в исходное дерево. Наша схема именования будет играть важную роль, позволяя нам быстро ориентироваться. Мы можем очень быстро перейти к файлу, введя фрагменты имени файла. Например, если имя вашего модуля forsee, вы можете увидеть список forsee файлов javascript, введя fo.js в поле поиска файлов (при условии, что ваш редактор поддерживает эту функцию). Эта функция встроена во вкладку "Исходный код" Chrome Dev Tools. Вы можете увидеть его в действии здесь ( откройте инструменты разработчика и нажмите Cmd+O):

Скриншот 1 поиска фрагментов

Раньше я думал, что для эффективного поиска необходимо предварять все имена файлов именем модуля, но потом понял, что это совсем не так. Мы можем так же эффективно искать fo/js:

Скриншот 2 поиска фрагментов

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


Обзорность

Я согласен с ExpertSystem в том, что группировка файлов позволяет вам лучше видеть вещи с первого взгляда. Тем не менее, еще раз добавлять имя модуля в начало не обязательно. Скорее активируйте соответствующую опцию в вашем редакторе:

Сортировать по типу снимка экрана

На снимке экрана выше я активировал параметр Сортировать по типу, чтобы включить сортировку файлов по их расширениям.


Почему мы не должны

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


Предостережения

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


Вывод

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


Кстати: я называю файлы js в соответствии с предложением ExpertSystems. То есть, dialog.js, dialog-ctrl.js, dialog-services.js и т. д. Это имеет смысл по причинам, которые он указал, но когда модуль имеет несколько частей, лучше не следовать этому шаблону именования для файлов html.

person Gil Birman    schedule 09.08.2014
comment
Большое тебе спасибо! Очень рад, что представлено другое мнение. Большинство из нас используют возвышенное и веб-шторм, и мы все еще обсуждаем название. - person alecxe; 09.08.2014
comment
Что касается организации (касательно связанной) ознакомьтесь с моим руководством по sass. Я не в восторге от размещения файлов css рядом с файлами javascript, потому что я думаю, что это поощряет использование CSS-кода, который менее пригоден для повторного использования в модулях. То есть я считаю, что CSS-модули и модули приложений следует рассматривать как две разные вещи. - person Gil Birman; 09.08.2014
comment
На этот вопрос есть продолжение: Организация проекта и соглашения об именах - действительно ценю вашу проницательность. Спасибо. - person alecxe; 11.09.2014

Все дело в организации больших проектов (кодовая база):


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

Исходя из мира ASP.NET, где проекты огромны, у нас есть:

Решения -> управление проектами (сборками) -> с помощью папок -> и подпапки для файлов.

Таким образом, проект ASP.NET MVC будет иметь контроллер Home в папке Controllers папки < em>Презентационный проект MVC и Views в папке Views.


При использовании AngularJS в своих проектах мне нравится подход к именованию

App(Module)-type(directive/service)-(sometimes more detail)

Это в дополнение к именованию папок для приложений и наличию директив и служб. в папках для их типов с папкой, названной в честь приложения, и приложением, часто названным функционально или в честь представления ASP.NET< /strong> (например, мой вид может быть Account-Login).

Все это потому, что мои проекты очень-очень большие. В итоге у меня много AngularJS apps, безумное количество directives и даже приличное количество services.

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

person Dave Alperovich    schedule 05.08.2014
comment
Я ненавижу проекты .NET, в которых много NameOfTheModuleController находится в одной папке. То же самое для просмотров. Я стараюсь всегда использовать области, где я могу поместить каждый контроллер в отдельную папку. - person LGama; 11.08.2014
comment
@LGama, я согласен с обоими мнениями. Корпоративные проекты никогда не перестают расти. Это не просто их предполагаемый размер или возможный размер. Вы в конечном итоге управляете абсурдным количеством кода. Преимущество избыточного именования состоит в том, что он сводит к минимуму недопонимание — мне бы не хотелось иметь несколько служб данных, не различая, к чему они применяются. - person Dave Alperovich; 11.08.2014
comment
На этот вопрос есть продолжение: Организация проекта и соглашения об именах - действительно ценю вашу проницательность. Спасибо. - person alecxe; 11.09.2014

Я написал об этом в одном из своих сообщений в блоге.

Модули часто имеют перекрывающиеся функции

Допустим, мы создавали страницу настроек учетной записи. Учетная запись admin может sendNotifications, тогда как учетная запись user может updateNotifications. Обе учетные записи admin и user могут updateAvatar.

Описывает функции, а также отношения

С компонентами, абстрагированными в отдельные модули, файлы и папки, легче работать.

Родительский объект, включающий все эти модули, может называться аккаунт. Мы знаем, что аккаунт будет иметь две разные роли и три разные функции. Если бы учетная запись была "независимой от ролей", ваше определение могло бы выглядеть примерно так:

angular.module("account",  [
  "account.updateAvatar",
  "account.sendNotifications", 
  "account.updateNotifications"
]);

Но определение родительских модулей для этих функций способствует организации и наследованию:

angular.module("account",  [
  "account.common",
  "account.admin", 
  "account.user"
]);

angular.module("account.common",  [
"account.common.updateAvatar"
]);

angular.module("account.admin",  [
"account.admin.sendNotifications"
]);

angular.module("account.user",  [
"account.user.updateNotifications"
]);

Модули функций могут следовать аналогичному шаблону:

angular.module("account.common.updateAvatar",  [ 
"account.common.updateAvatar.services",  
"account.common.updateAvatar.controllers",  
"account.common.updateAvatar.directives",
"account.common.updateAvatar.filters"
]);

Просмотры и активы:

account.common.updateAvatar.less
account.common.updateAvatar.tpl.html
account.common.updateAvatar.heading.tpl.html
account.common.updateAvatar.body.tpl.html

Точечная нотация может включать простые шаблоны подстановки

Скомпилируйте все части вашего HTML в кешированный JavaScript:

module.exports = function(grunt) {
  grunt.initConfig({
    html2js: {   
      partials: {
        src: ["src/**/*.tpl.html"],
        dest: "build/js/app.tpls.js",
        module: "app.tpls"
      }
    }
  )};
};

Объединить весь ваш admin JavaScript независимо от вашего user JavaScript:

module.exports = function(grunt) {
  grunt.initConfig({
    concat: {
      admin: {
        src: ["src/**/*.admin.*.js"],
        dest: "build/js/admin.js"
      },
      user: {
        src: ["src/**/*.user.*.js"],
        dest: "build/js/user.js"
      }
  )};
};
person Dan Kanze    schedule 19.08.2014
comment
На этот вопрос есть продолжение: Организация проекта и соглашения об именах - действительно ценю вашу проницательность. Спасибо. - person alecxe; 11.09.2014

Как заявила ExpertSystem, ваша текущая структура каталогов не связана с блогом Рекомендации по лучшей практике для Структура приложения Angular.

Я согласен с ExpertSystems, а также с Гилом Бирманом, что подход к разработке структуры приложения должен быть модульным. Как вы знаете, сам Angular следует модульной структуре, поэтому независимо от того, есть ли у вас несколько модулей или один модуль Angular, вам нужно думать в соответствии с функциональностью, которую вы обслуживаете. Например, если у вас есть функция «Обратный отсчет», она должна иметь собственную структуру.

Почему это важно?

<сильный>1. Сопровождение кода: по мере роста вашего кода ваши затраты на обслуживание растут. Если, например, в производственной среде вы получаете ошибку в своем коде angular и хотите исправить ее с KRA в 1 час, вам сначала нужно будет реплицировать сценарий локально, а затем перейти к этому конкретному файлу. Если бы это был модуль, вы бы знали, на какую папку ориентироваться, и быстро получили бы решение.

<сильный>2. Простота разработки: вы можете разделить несколько функций между несколькими разработчиками, и они могут ориентироваться на разные функциональные папки, чтобы они не касались одних и тех же файлов. Конфликты слияния могут быть уменьшены.

<сильный>3. Более быстрые проверки: поскольку приложение разбито на функции, проверки можно выполнять быстрее и с легкостью, зная, что код для этой папки предназначен для этой конкретной функции.

<сильный>4. Реализация TDD: структуру можно использовать для запуска разработки через тестирование (TDD). Преимущества TDD упоминаются здесь, в этой статье.

Разница между кодом/структурой разработки и производства

В разработке вы можете иметь структуру в соответствии с функциональностью. Однако для повышения производительности вашего веб-приложения (или гибридного мобильного приложения) лучший способ сделать это — объединить все файлы, минимизировать их и запутать с помощью ГРЮТ. Для этого будет предоставлен образец файла GRUNT. Вы можете запускать скрипт каждый раз во время развертывания, используя любой инструмент непрерывной интеграции, такой как, например, Jenkins.

person V31    schedule 20.09.2014