Лучшая система именования и организации файлов

Проклятие и дар React.js заключается в том, что он не самоуверен в том, как вы структурируете свои компоненты и файлы. Делайте, что хотите, и это сработает. Но с каждым новым проектом это проблема «чистого листа».

Эта статья написана с точки зрения человека, создающего (и, наконец, рефакторинга) интерфейса платформы для ведения блогов, предназначенной для энтузиастов пленочной фотографии. Помимо перечисления и отображения статей, приложение предоставляет административные элементы управления и полный набор редакторов форматированного текста, состоящий из 280 файлов и папок. Речь идет о приложении Analog.Cafe.

Предисловие 1: «глупые» и «умные» компоненты: не лучший способ сортировать файлы.

- app/
  - components/
  - containers/

Когда я начал работать над своим приложением после года интенсивных сборок Ruby on Rails для Archie.AI (довольно самоуверенный фреймворк), я упал на стену, пытаясь выяснить, как структурировать и назвать многочисленные файлы с помощью React. . В то время наиболее распространенным советом было разделить компоненты на чистые функции и компоненты с отслеживанием состояния.

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

Поразмыслив, я придумал лучшую систему (см. Ниже).

Предисловие 2: стилизованные компоненты, это не CSS; они компоненты.

Styled-components - моя любимая библиотека, когда дело касается встраивания CSS в проекты React. Это очень хорошо.

Распространенной схемой его использования является разделение стилей на styles.js, что напоминает файловую структуру, которая не так давно была у нас с более простыми рукописными файлами HTML.

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

Я рекомендую рассматривать стилизованные компоненты так, как они есть - компоненты React.

Шаблон интерфейса.

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

Форма структуры файлов и папок.

- app/
  - core/
  - admin/
  - user/
  - constants.js
  - index.js
  - store.js
  - utils.js

Примечание: вы можете просмотреть всю структуру приложения для Analog.Cafe в этом репозитории.

Мое приложение разделено на три основных раздела: core/ admin/ и user/. В вашем случае у вас может не быть никаких разделов, если приложение недостаточно велико. Затем вы можете структурировать свою папку app/ так же, как содержимое приведенных выше разделов (см. Ниже).

Приведенные выше четыре файла JavaScript не требуют пояснений, но с некоторыми оговорками. В этом примере они служат индексными файлами, в которых хранятся только самые основные и часто используемые экспорты: index.js содержит основной компонент React оболочки для приложения, store.js объединяет редукторы, найденные внутри трех вышеуказанных приложений. разделов и экспортирует хранилище Redux, а utils.js и constants.js содержат наиболее распространенные фрагменты функций JavaScripit и повторно используемые константы.

- core/
  - components/
  - constants/
  - store/
  - utils/

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

Если вы не разбиваете приложение на разделы, указанные выше папки можно поместить в папку app/ вместо core/.

- constants/
  - messages-.js
  - messages-article.js
  - routes-article.js
  - rules-submission.js
- utils/
  - actions-session.js
  - messages-profile.js

Обе папки constants/ и utils/ имеют похожие шаблоны именования файлов. Первое ключевое слово - это сообщения, маршруты, правила или действия. За ним следует тире и ключевое слово, описывающее определенную часть представления вашего приложения. Я понимаю, что это не самое надежное соглашение об именах, однако вы можете лучше понять его на практике. Основными целями должны быть последовательность и ясность.

Обратите внимание на файл с именем messages-.js, который содержит строки и объекты, обозначенные как сообщения, обращенные к пользователю, не назначенные какой-либо конкретной части представления приложения.

- store/
  - actions-article.js
  - actions-submission.js
  - reducers-article.js
  - reducers-submission.js

Папка store/ предназначена для Redux. Он содержит пары файлов (действия и редукторы) для каждой части вашего приложения. Простой; все в одном месте.

- components/
  - controls/
  - icons/
  - pages/
  - routes/
  - forms/
  - vignettes/

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

controls/ - Кнопки и массивы кнопок, модальные поля, ссылки, панели навигации, меню и т. д.

icons/ - Графические элементы, созданные с помощью React и предназначенные для того, чтобы оставаться частью приложения, например, встроенные SVG или CSS.

pages/ - Компоненты, которые должны занимать целую или значимую часть экранного пространства.

routes/ - Эта папка предназначена специально для компонентов маршрута React Router.

forms/ - Элементы ввода.

vignettes/ - Компоненты меньшего размера, которые больше нигде не нужны.

- controls/
  - Card/
    - index.js
    - components/
      - CardFigure.js
      - CardHeader.js

Каждая из компонентных папок будет иметь имена, написанные в CamelCase, с необязательным index.js в их корне, который будет связывать все вместе. При необходимости внутри можно разместить папку components/, которая может содержать стилизованные компоненты или компоненты React.js, которые напрямую помогли бы составить основной компонент (в данном случае Card/ component).

Примечание 1. Здесь нет различия или правил между «умными» и «глупыми» компонентами, но «умные» компоненты, естественно, обычно оказываются в корне основного компонента в индексе. .js, который можно использовать в своих интересах.

Примечание 2: Вам ничего не мешает импортировать файлы из других разделов приложения; в большинстве случаев это требуется, и в этом нет ничего плохого. Не стесняйтесь требовать admin/ утилит в core/ компонентах.

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

Предпочтительные типы экспорта.

Простое правило - предпочитать именованный экспорт, например export const function Name ()=>{} в constants/ utils/ и store/ - это побудит вас правильно сбалансировать количество файлов в этих папках.

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

Рекомендации по размеру файла.

Не более 300 строк в файле. Все, что больше этого, требует разделения.

Комментирующие практики.

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

Напишите читаемый код вместо того, что вам нужно в руководстве.

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

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

🍻

Первоначально опубликовано на www.archie.ai.