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

Известната публикация в блога Препоръки за най-добри практики за структура на ъглово приложение очертава новата препоръчителна структура на проекта 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".
Той се намира в първия файл, чието име е значително по-дълго от предишните файлове.
Услугата (ако има такава) се намира във файла с по-малко име в края и т.н.

Объркайте това (т.е. объркайте реда поради началната буква или объркайте относителната им дължина поради дълги/къси имена на компоненти) и ще имате ситуация, подобна на това, че трябва да прочетете нещо от твърдия диск, вместо просто да четете от RAM паметта. (Никой програмист не иска да отиде там :))


*: Всъщност тук е важно това, което наричаме „поток на екипа на разработчиците“, т.е. колко често член на екипа ще напуска (напр. за да работи върху нещо друго, напускане на компанията и т.н.) или ще бъде представен нов член .
Обикновено колкото по-голям е екипът, толкова по-голям е потокът.

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, че групирането на файлове заедно ви позволява да видите нещата по-добре с един поглед. Обаче още веднъж добавянето на името на модула преди не е наистина необходимо. По-скоро активирайте подходящата опция във вашия редактор:

Сортиране по тип екранна снимка

На екранната снимка по-горе активирах опцията Сортиране по тип, за да активирам сортирането на файлове по техните файлови разширения.


Защо не трябва

Ако кодирате на малък екран (т.е. лаптоп) и използвате дървовиден изглед отляво за навигация в структурата на папките, ограниченото пространство на екрана ще бъде по-добре обслужвано от по-кратки имена на файлове. Името на папката на модула ще бъде видимо, така че не е полезно това име да се повтаря за всеки файл.


Предупреждения

Очевидно повечето от това, което представих по-горе, разчитат на разработчиците, които използват правилните инструменти и знаят как да ги използват добре. Ако вашият екип не разполага с тези инструменти или се съмнявате в способността им да ги използват ефективно, обучете ги или се придържайте към схемата за многословно именуване.


Заключение

С усъвършенстваните инструменти, достъпни за разработчиците днес, повтарянето на името на модула за всеки файл е анахронизъм. Прекалено многословното именуване на файлове обаче не причинява голяма вреда или проблеми с ефективността. Когато структурираме нов проект, има много други архитектурни решения, които ще трябва да вземем, които са много по-важни от това.


BTW: Именувам js файлове според предложението на ExpertSystems. Т.е., dialog.js, dialog-ctrl.js, dialog-services.js и т.н. Това има смисъл поради посочените от него причини, но когато един модул има множество части, най-добре е да не следвате този модел на именуване за html файлове.

person Gil Birman    schedule 09.08.2014
comment
Благодаря ти много! Наистина се радвам, че има различно мнение. Повечето от нас използват sublime и webstorm и все още обсъждаме именуването. - 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 в папката Изгледи.


Когато използвам AngularJS в моите проекти, харесвам подхода на именуване

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

Това е в допълнение към именуване на папки за приложения и наличие на директиви и услуги в папки за техните типове с папката, наречена след приложението и приложението, често именувано функционално или след ASP.NET View< /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

Писах за това в една от моите публикации в блог

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

Да речем, че създаваме страница с настройки на акаунта. Административният акаунт може sendNotifications, където потребителският акаунт може updateNotifications. Както администратор, така и потребител акаунти могат 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"
      }
    }
  )};
};

Свържете целия си администраторски JavaScript независимо от вашия потребителски 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, както и с Gil Birman, че подходът за проектиране на структурата на приложението трябва да бъде модулен. Както знаете, самият Angular следва модулна структура, така че независимо дали имате няколко модула или един модул Angular, трябва да мислите според функционалността, която обслужвате. Например, ако имате функция „CountDown“, тя трябва да има своя собствена структура.

Защо това е важно?

1. Поддръжка на код: С нарастването на кода ви разходите за поддръжка растат. Ако например в производствената среда получите грешка във вашия angular код и искате да коригирате с KRA от 1 час, първо ще трябва да копирате сценария локално и след това да преминете към този конкретен файл. Ако беше модул, щеше да знаеш към коя папка да се насочиш и бързо получи решението.

2. Лесно разработване: Можете да разделите множество функции между множество разработчици и те могат да насочват към различни функционални папки, така че да не докосват едни и същи файлове. Сливането на конфликти може да бъде намалено.

3. По-бързи прегледи: Тъй като приложението е разделено на функционалности, прегледите могат да се извършват по-бързо и с лекота, като се знае, че кодът за тази папка е за тази конкретна функционалност.

4. Внедряване на TDD: Структурата може да се използва за стартиране на разработка, управлявана от тестове (TDD). Ползите от TDD са споменати тук в тази статия

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

В Разработка можете да имате структура според функционалността. Въпреки това, за да подобрите производителността на вашето уеб приложение (или хибридно мобилно приложение), най-добрият начин да направите това е да обедините всички файлове, да ги минимизирате и да ги скриете с помощта на GRUNT. Ще даде извадка от файла GRUNT за същото. Можете да стартирате скрипта всеки път по време на внедряване, като използвате всеки инструмент за непрекъсната интеграция, като Jenkins например.

person V31    schedule 20.09.2014