├── CSS
    └── README.md
├── Environment
    ├── README.md
    ├── branches-and-requests.md
    ├── conventional-commits.md
    ├── husky.md
    └── lint-staged.md
├── HTML
    └── README.md
├── Initiation.md
├── JS
    └── README.md
├── README.md
└── React
    ├── Optimization.md
    └── README.md


/CSS/README.md:
--------------------------------------------------------------------------------
  1 | # CSS
  2 | 
  3 | 1. [Общие требования](#1)
  4 | 2. [Правила](#2)
  5 | 3. [Шрифты](#3)
  6 | 4. [БЭМ](#4)
  7 | 5. [Возможные ошибки](#5)
  8 | 
  9 | <a name="1"></a>
 10 | 
 11 | ## Общие требования
 12 | 
 13 | <a name="1.1"></a>
 14 | 
 15 | - [1.1](#1.1) Главное! Используем [pixel-perfect](https://chrome.google.com/webstore/detail/perfectpixel-by-welldonec/dkaagdgjmgdmbnecmcefdhjekcoceebi?hl=ru), если заказчик предоставил макет.
 16 | 
 17 | <a name="1.2"></a>
 18 | 
 19 | - [1.2](#1.2) Не подключать стили с удаленных источников — только с наших серверов.
 20 | 
 21 | <a name="1.3"></a>
 22 | 
 23 | - [1.3](#1.3) CSS — опасная сила.
 24 | 
 25 |   Все стили, подключаемые к странице, являются глобальными, и, если этим злоупотреблять, то можно легко довести проект до состояния крайне болезненного внедрения любого нового элемента или изменения старого. Это чаще всего происходит, когда создаются "общие" классы, потом крепятся к разным элементам на странице (банальный пример — шапка, у которой внутри форма поиска, которая есть на всех страницах с одинаковыми классами) и в итоге, когда по дизайну на разных страницах появляются небольшие отличия в шапке, плодятся классы, переписывающие свойства. И так почти для всех элементов каждой страницы. В итоге, меняя крайнюю правую ссылку в сайдбаре на странице новостей, вы можете поломать верстку всего сайдбара на какой-нибудь другой странице, например, на странице личного кабинета.
 26 | 
 27 |   Для того чтобы такого не происходило, существуют разные методологии, например, `БЭМ` (прочитать про него обязательно хотя бы в общих чертах) или, например, [rscss](https://ricostacruz.com/rscss/index.html). Для начала можете изучить [небольшой подход](https://isobar-us.github.io/code-standards/), который используют ребята из `Isobar` — он описан в рамках их стандарта и состоит из 7 небольших абзацев. 
 28 | 
 29 |   Для решения проблемы уникальности имён классов на программном уровне, мы используем [CSS Modules](https://github.com/css-modules/css-modules). Некоторые разработчики предпочитают [styled-components](https://styled-components.com/) или [tailwindcss](https://tailwindcss.com/).
 30 |   
 31 | 
 32 | <a name="1.4"></a>
 33 | 
 34 | - [1.4](#1.4) Отступы делать пробелами, один уровень — 2 пробела.
 35 | 
 36 | <a name="1.5"></a>
 37 | 
 38 | - [1.5](#1.5) Использовать одинарные кавычки.
 39 | 
 40 | <a name="1.6"></a>
 41 | 
 42 | - [1.6](#1.6) Перед началом работы обязательно четко знать все приоритеты селекторов и все 4 вида возможных отношений.
 43 | 
 44 |   Отношения элементов между собой могут быть:
 45 | 
 46 |   - `div p` – элементы p, являющиеся потомками div
 47 |   - `div > p` – только непосредственные потомки
 48 |   - `div ~ p` – правые соседи: все p на том же уровне вложенности, которые идут после div
 49 |   - `div + p` – первый правый сосед: p на том же уровне вложенности, который идёт сразу после div (если есть)
 50 | 
 51 |   А про приоритеты можно почитать [здесь](https://habrahabr.ru/post/137588/) и во многих других местах.
 52 | 
 53 | <a name="1.7"></a>
 54 | 
 55 | - [1.7](#1.7) Не использовать `@import` внутри файлов.
 56 | 
 57 |   Имеется в виду, что в конечном `css` файле, который получает клиент, не должно быть этих конструкций. Но если настроен `WebPack` и `css-loader`, который как раз этот случай обрабатывает, либо используются компилируемые аналоги, которые умеют вместо импортов подставлять непосредственное содержимое файлов, то импорты возможны, так как браузер все равно их не увидит и не получит никогда в реальной работе.
 58 | 
 59 |   Можно выделить пару причин, почему не стоит использовать `@import`:
 60 | 
 61 |   - Некоторые старые браузеры не поддерживают использование правила `@import`, и стили, которые мы подгружаем через это правило, будут потеряны
 62 |   - `@import` блокирует параллельную загрузку стилей, а это означает, что браузер будет ожидать завершения загрузки импортированного файла, прежде чем начнёт обрабатывать остальную часть содержимого.
 63 |   - Более подробно можно почитать [здесь](http://www.stevesouders.com/blog/2009/04/09/dont-use-import/).
 64 | 
 65 | <a name="1.8"></a>
 66 | 
 67 | - [1.8](#1.8) Все правила должны быть разбиты на разные файлы по страницам и блокам, каждый файл должен быть не длиннее, чем 1000 строк.
 68 | 
 69 | <a name="1.9"></a>
 70 | 
 71 | - [1.9](#1.9) Каждое CSS-правило должно быть на отдельной строке.
 72 | 
 73 |   Это очень поможет как минимум при просмотре diff-ов в системе контроля версий. Плюс это позволит избежать горизонтальной прокрутки.
 74 | 
 75 | <a name="1.10"></a>
 76 | 
 77 | - [1.10](#1.10) Для всех интерактивных элементов (ссылки, кнопки, дропдауны, инпуты, селекты) дизайнер может прорисовать отдельные состояния и спрятать в ближайшем слое — всегда проверять для каждого элемента, есть ли отрисованное состояние.
 78 | 
 79 | <a name="1.11"></a>
 80 | 
 81 | - [1.11](#1.11) Дизайнеры могут ошибаться — иногда надо делать запросы на изменение макета, если они нарисовали что-то переусложненное.
 82 | 
 83 |   Например, в макете может быть отцентрированная по вертикали относительно текста полоска:
 84 | 
 85 |   | ![Пример](https://user-images.githubusercontent.com/12808495/55335190-df687980-54c4-11e9-8623-13ecdb996ebc.png) |
 86 |   | :-------------------------------------------------------------------------------------------------------------: |
 87 |   |                       _эта картинка просто пример, не факт, что тут как раз такая ошибка_                       |
 88 | 
 89 |   Дизайнер может просто на глаз положить эту полоску на среднем уровне нижних букв текста, однако вы как верстальщики просто примените vertical-align: middle и увидите, что полоска выше/ниже уровня, который показал дизайн, и Pixel Perfect явно это подсвечивает. Чаще всего не надо хардкодить какой-нибудь неочевидный отступ, просто чтобы идеально соответствовать макету — лучше сказать дизайнеру, что автоматом полоска ставится на другое место и её лучше там и оставить. А дизайнеру подучить типографику.
 90 | 
 91 | <a name="1.12"></a>
 92 | 
 93 | - [1.12](#1.12) Пытаться по максимуму делать сайт резиновым (ставьте ширину в процентах и выставляйте max-width, min-width) — прибегайте к фиксированной ширине элемента, только если по макету от этого никак не уйти.
 94 | 
 95 |   Если все-таки сайт должен быть с фиксированный шириной, обязательно проверяйте правую сторону каждой страницы на маленьких экранах. Очень частая ошибка новичков не все элементы делать с min-width, и при горизонтально прокрутке получается такая штука:
 96 | 
 97 |   ![image](https://rizzoma.com/r/files/a87a0a28b84d6326d4f3909e8801dab7-60dd9b15a5f2c5e495726e74545edcae-0-0.7016728184648524)
 98 | 
 99 | <a name="1.13"></a>
100 | 
101 | - [1.13](#1.13) При сборке проекта при отсутствии дизайна (на CSS-фреймворках, например) избегать "лепки".
102 | 
103 |   Если вы разрабатываете проект, у которого нет дизайна (при помощи CSS-фреймворков, например), то старайтесь избегать лепки.
104 | 
105 |   Правила те же, что и при написании программных модулей: старайтесь придать пространства между компонентами, ограничить их друг от друга визуально (осуществляется слабое зацепление), но вместе с этим, сами компоненты должны выглядеть самодостаточно, т.е. обладать всем необходимым, но без избыточности, функционалом, чтобы это можно было назвать полноценной компонентой (осуществляется сильная связанность).
106 | 
107 |   Хорошим детектором является тут БЭМ: старайтесь делать отступы между блоками минимум в два раза больше, чем внутри блока между элементами.
108 | 
109 | <a name="1.14"></a>
110 | 
111 | - [1.14](#1.14) Все стили одного блока должны быть в одном месте и отсортированы по порядку их расположения на странице.
112 | 
113 |   То есть, если есть шапка, а внутри нее поисковая форма, то в .css файлах нельзя сначала определить стили шапки, потом кучу стилей тела страницы и потом стили поисковой формы шапки. Должны идти стили самой шапки и сразу под ней стили формы.
114 | 
115 |   При этом стили сайдбара не могут идти раньше стилей шапки, а стили футера идти раньше стилей сайдбара. Лучше вообще эти стили разнести по разным файлам.
116 | 
117 | <a name="1.15"></a>
118 | 
119 | - [1.15](#1.15) Футер страницы должен быть всегда прижат к низу страницы, даже если на странице мало контента ([5 методов, как сделать это](http://dimox.name/press_footer_bottom_with_css/)).
120 | 
121 | <a name="1.16"></a>
122 | 
123 | - [1.16](#1.16) Имена.
124 | 
125 |   Использовать `lower-case-hyphenated` (то есть не `mySuperAwesomeElement` и не `my_super_awesome_element`)
126 | 
127 |   Имена должны отражать смысл, а не описание стилей (`"loading"`, а не `"big-yellow-spinny-thing"`)
128 | 
129 | <a name="2"></a>
130 | 
131 | ## Правила
132 | 
133 | <a name="2.1"></a>
134 | 
135 | - [2.1](#2.1) Не использовать `!important`.
136 | 
137 |   В 99% случаях проблему можно решить, грамотно используя `БЭМ` или `CSS modules`. В сложных редких случаях лучше увеличивать приоритет селекторов (например, когда надо стили библиотеки переопределить).
138 | 
139 | <a name="2.2"></a>
140 | 
141 | - [2.2](#2.2) Не использовать `position: absolute` для стилизации, где это можно заменить другими подходами.
142 | 
143 | <a name="2.3"></a>
144 | 
145 | - [2.3](#2.3) Не двигать элемент при помощи `top`, `left`, `right` или `bottom` при `position: relative`, где это можно заменить другими подходами.
146 | 
147 |   Можно использовать сам `position: relative` (без свойств `top`, `left`, `right` или `bottom`) для `z-index` и для того, чтобы указать потомкам элемента ориентир.
148 | 
149 | <a name="2.4"></a>
150 | 
151 | - [2.4](#2.4) Не использовать отрицательные margin.
152 | 
153 |   На самом деле, отрицательные `margin` — это валидные правила, они поддерживаются спецификацией `CSS`, и их даже используют такие гиганты, как Bootstrap (посмотрите стили для `.row`).
154 | 
155 |   Но это очень неочевидные правила, их тяжело обнаружить, и их почти всегда можно заменить более легкими и предсказуемыми свойствами.
156 | 
157 | <a name="2.5"></a>
158 | 
159 | - [2.5](#2.5) Избегать фиксирования высоты.
160 | 
161 |   Почти всегда использование фиксированного в пикселях, процентах и других единицах `height` является признаком неправильного кода. Это делает очень неочевидным поведение элементов, которые следуют за зафиксированным по высоте, может произойти обрезание контента или его наложение на следующие элементы.
162 | 
163 |   Когда это все-таки может быть нужно:
164 | 
165 |   - У элемента надо ручками подстроиться под высоту потомков, которых "убрали" из общего потока. "Убрать" из потока можно через `position: absolute`, например. Это может быть слайдер, у которого потомки крутятся как раз через позиционирование, а не смещение `margin`-ом
166 | 
167 |   - По дизайну надо подстроить все элементы под определенную высоту, а контент, вылезающий за пределы, обрезать.
168 | 
169 | <a name="2.6"></a>
170 | 
171 | - [2.6](#2.6) Избегать фиксированных выравниваний.
172 | 
173 |   Если блок должен быть отцентрирован (хоть по горизонтали, хоть по вертикали), то центрировать его динамически, а не фиксированным `margin-top`.
174 | 
175 |   Например:
176 | 
177 |   ![Пример](https://user-images.githubusercontent.com/12808495/55335190-df687980-54c4-11e9-8623-13ecdb996ebc.png)
178 | 
179 |   Здесь картинку, текст и полоску надо центрировать через `vertical-align`, а не `top: 55px` у полоски.
180 | 
181 |   Часто будут попадаться случаи более сложного центрирования — почти для каждого есть свой метод, надо их отдельно изучать.
182 | 
183 |   [Статья про vertical-align](http://web-standards.ru/articles/vertical-align/)
184 | 
185 |   Что нужно сделать, чтобы центрировать по высоте _элемент1_ внутри _элемента2_:
186 | 
187 |   - Оба элемента должны быть любыми inline элементами
188 | 
189 |   - У _элемента2_ должен быть указан font-size или line-height. _Элемент2_ отцентрируется только в зависимости от font-size или line-height и не обратит внимания на height.
190 | 
191 | <a name="2.7"></a>
192 | 
193 | - [2.7](#2.7) Прописывать дефолтный цвет фона, цвет шрифта, `font-size` и семейство шрифта у `html`.
194 | 
195 |   Далее размер шрифта будет ориентиром для всех элементов, у которых используется rem для единиц измерения кегля.
196 | 
197 | <a name="2.8"></a>
198 | 
199 | - [2.8](#2.8) При тестировании обязательно посмотреть цвет `:visited` ссылки.
200 | 
201 |   Браузер по умолчанию такие ссылки фиолетовыми делает, что чаще всего недопустимо в дизайне.
202 | 
203 | <a name="2.9"></a>
204 | 
205 | - [2.9](#2.9) Добавлять элементу `cursor: pointer`, если он кликабелен и по умолчанию этого не поддерживает.
206 | 
207 | <a name="2.10"></a>
208 | 
209 | - [2.10](#2.10) Удалять все неиспользуемые правила и правила, которые никак не влияют на отображение (например, дублирующие свойства по умолчанию или нулевые `margin`, если они и так не выставлены) — они могут в дальнейшем при правках внести неочевидное поведение и из-за них тяжело разбираться в проекте.
210 | 
211 | <a name="2.11"></a>
212 | 
213 | - [2.11](#2.11) Слова, целиком состоящие из верхнего регистра, предпочтительно делать через стиль `text-transform: uppercase`, а не реальным вводом текста заглавными буквами.
214 | 
215 | <a name="2.12"></a>
216 | 
217 | - [2.12](#2.12) При установке элементу `outline: none` обязательно выставить стили для `:focus` этому элементу.
218 | 
219 |   `outline` очень полезен, когда юзер заполняет форму, используя клавишу `tab` для переключения между инпутами и кнопками. Если `outline` убрать, станет менее заметно (или незаметно вовсе для кнопок), какой элемент сейчас выбран.
220 | 
221 | <a name="2.13"></a>
222 | 
223 | - [2.13](#2.13) Все использования `@media` должны идти сразу после основных правил элемента, для того чтобы можно было увидеть все правила и все возможные состояния элемента в одном экране без прокручивания.
224 | 
225 | <a name="2.14"></a>
226 | 
227 | - [2.14](#2.14) Вендорные префиксы должны идти перед общим стилем.
228 | 
229 |   Стандартное правило всегда должно быть под специфичными правилами для каждого движка.
230 | 
231 |   Пример:
232 | 
233 |   ```css
234 |   .thing {
235 |     -webkit-transition: all 100ms;
236 |     -moz-transition: all 100ms;
237 |     -o-transition: all 100ms;
238 |     transition: all 100ms;
239 |   }
240 |   ```
241 | 
242 | <a name="3"></a>
243 | 
244 | ## Шрифты
245 | 
246 | <a name="3.1"></a>
247 | 
248 | - [3.1](#3.1) Если клиент предоставил макеты с кастомными шрифтами, проверить, свободные ли они и, если нет, то запросить купленные файлы шрифтов.
249 | 
250 | <a name="3.2"></a>
251 | 
252 | - [3.2](#3.2) Если не требуется поддержка старых браузеров, шрифты должны быть в форматах `.woff2`, `.woff`. Сначала подключать `.woff2` шрифты, затем — `.woff` (пример ниже).
253 | 
254 | <a name="3.3"></a>
255 | 
256 | - [3.3](#3.3) Если в проекте должна быть поддержка нелатинских символов (например, русских), проверьте, что в файле шрифта эти символы есть.
257 | 
258 | <a name="3.4"></a>
259 | 
260 | - [3.4](#3.4) Разные начертания одного и того же шрифта подключайте под одним именем, но для разных `font-weight` и `font-style`.
261 | 
262 |   ```css
263 |   @font-face {
264 |     font-family: "Lato";
265 |     src: url("../fonts/lato-regular.woff2"), url("../fonts/lato-regular.woff");
266 |     font-weight: 400;
267 |     font-style: normal;
268 |   }
269 |   @font-face {
270 |     font-family: "Lato";
271 |     src: url("../fonts/lato-italic.woff2"), url("../fonts/lato-italic.woff");
272 |     font-weight: 400;
273 |     font-style: italic;
274 |   }
275 |   @font-face {
276 |     font-family: "Lato";
277 |     src: url("../fonts/lato-light.woff2"), url("../fonts/lato-light.woff");
278 |     font-weight: 300;
279 |     font-style: normal;
280 |   }
281 |   @font-face {
282 |     font-family: "Lato";
283 |     src: url("../fonts/lato-lightitalic.woff2"),
284 |       url("../fonts/lato-lightitalic.woff");
285 |     font-weight: 300;
286 |     font-style: italic;
287 |   }
288 |   ```
289 | 
290 | <a name="3.5"></a>
291 | 
292 | - [3.5](#3.5) Всегда использовать как минимум один запасной шрифт и одно запасное семейство.
293 | 
294 |   Их перечисляют через запятую в `font-family`, так что каждое использование `font-family` должно происходить по схеме:
295 | 
296 |   ```css
297 |   block {
298 |     font-family: Helvetica, Arial, sans-serif;
299 |   }
300 |   ```
301 | 
302 |   Здесь `Helvetica` — нестандартный подключаемый шрифт.
303 | 
304 |   `Arial` — стандартный шрифт, который используется почти на всех клиентах, он будет использоваться, если не удалось подключить `Helvetica`.
305 | 
306 |   `sans-serif` — это семейство всех шрифтов без засечек (каковыми являются и `Helvetica`, и `Arial`). Если даже `Arial-а` на компе нет, то поставится какой-то системный дефолтный шрифт без засечек. Выбор здесь надо делать из `"serif,"` `"sans-serif,"` или `"monospace"`. Для шрифтов без засечек использовать по умолчанию `Arial`, для шрифтов с засечками — `Georgia` (а не `Times New Roman`), а для моноширинных — `"Courier New"`
307 | 
308 | <a name="3.6"></a>
309 | 
310 | - [3.6](#3.6) Названия шрифтов, содержащие пробелы, цифры или знаки пунктуации, кроме дефисов, заключать в кавычки.
311 | 
312 |   Пример:
313 | 
314 |   ```css
315 |   block {
316 |     font-family: 'Times New Roman', serif;
317 |   }
318 |   ```
319 | 
320 | <a name="4"></a>
321 | 
322 | ## БЭМ
323 | 
324 | <a name="4.1"></a>
325 | 
326 | - [4.1](#4.1) Именование БЭМ-сущностей должно следовать следующим ограничениям:
327 | 
328 |   Блок, элемент — всегда имя существительное (noun)
329 | 
330 |   Модификатор — должен удовлетворять свойствам [модификатора из английского языка](https://en.wikipedia.org/wiki/Grammatical_modifier). Всегда `adjective` или `adjectival phrase`.
331 | 
332 |   Таким образом, фразы на английском языке `"$BLOCK_NAME [is] $MODIFIER_NAME"`, `"$ELEMENT_NAME [is] $MODIFIER_NAME"` или `"$MODIFIER_NAME $BLOCK_NAME"`, `"$MODIFIER_NAME $ELEMENT_NAME"`, `"$ELEMENT_NAME WITH $MODIFIER_NAME $MODIFIER_KEY"` должны быть синтаксически корректными словосочетаниями.
333 | 
334 |   Примеры _корректных имён_:
335 | 
336 |   - `input_selected` — `selected input` — выделенный инпут или `input is selected` — инпут выделен
337 |   - `header_size_large` — `header with large size` — заголовок с большим размером.
338 | 
339 |   Примеры _**НЕ**корректных имён_:
340 | 
341 |   - `form__`**_save_**`_small`, для элемента save (который, например, вешается на кнопку) — `small save` — маленький сохранить, `save small` — сохранить маленький. Правильно будет употребить noun вместо `verb` и переименовать элемент в **_`save-button;`_** `small save-button` — маленькая кнопка сохранения
342 | 
343 |   - `input_`**_focus_** — `input focus` — инпут сфокусировать или `input is focus` — инпут это фокус. Правильно будет употребить `adjective` вместо `noun/verb` и переименовать модификатор в `focused; input_`**_focused_** — `focused input` — сфокусированный инпут
344 | 
345 |   - `row_`**_error_** — `row error` — ошибка строки или `row is error` — строка это ошибка. Правильно будет употребить `adjectival phrase` вместо `noun` и переименовать модификатор в `with-error`. `row_`**_with_**`-error` — `row with error` — строка с ошибкой.
346 | 
347 |   Обоснование: мы сможем всегда однозначно и без лишних затрат энергии истолковать сущность элемента вёрстки и накладываемые на него свойства.
348 | 
349 | <a name="4.2"></a>
350 | 
351 | - [4.2](#4.2) Верстаем всегда по БЭМу, архитектура верстки должна быть компонентной.
352 | 
353 |   Каждый блок должен лежать в своей папке.
354 | 
355 |   Папки блоков нельзя вкладывать друг в друга.
356 | 
357 | <a name="4.3"></a>
358 | 
359 | - [4.3](#4.3) Каждый компонент — отдельный блок из методологии БЭМ.
360 | 
361 | <a name="4.4"></a>
362 | 
363 | - [4.4](#4.4) Каждый компонент должен иметь только явные зависимости, быть самодостаточным.
364 | 
365 |   Все зависимости делать явно, импортируя в начале компонента и вставляя в нужное место верстки.
366 | 
367 |   Самодостаточность говорит о том, что каждый компонент должен внутри себя содержать все необходимое — всю верстку, все стили и все js-скрипты.
368 | 
369 |   Ничего лишнего в компоненте быть не должно:
370 | 
371 |   - Не должно быть определения других блоков внутри этого блока
372 |   - Не должно быть стилей, которые бы влияли на другие блоки любым способом
373 |   - Не должно быть глобальных стилей (например, на все теги `span`)
374 |   - Компонент не должен влиять на `DOM` другого компонента (менять верстку крайне запрещено)
375 | 
376 | <a name="4.5"></a>
377 | 
378 | - [4.5](#4.5) Кастомизировать компоненты только через модификаторы, никаких примесей.
379 | 
380 |   Почти в любом проекте возникает необходимость кастомизировать блоки. Например, есть вёрстка из 20 страниц. На 15 из этих страниц встречается хэдер, причём у 10 из них хэдер синего цвета, на трёх — серый, и на двух — прозрачный. Это значит, что компонент хэдер должен быть кастомизируемым, и осуществляются подобного рода кастомизации через добавление модификаторов к блоку, а не путём передачи отдельных классов со стилями.
381 | 
382 |   Предположим, что на фоне у промо страницы есть видео, и по дизайну нам нужно сделать прозрачный хэдер со светлым шрифтом (по умолчанию — тёмный).
383 | 
384 |   Плохо:
385 | 
386 |   ```pug
387 |   .promo-page
388 |     +header({ classname: 'promo-page__header' })
389 |   ```
390 | 
391 |   Хорошо:
392 | 
393 |   ```pug
394 |   .promo-page
395 |     +header({ theme: 'transparent', font: 'light' })
396 |   ```
397 | 
398 |   При правильном подходе, естественно, надо будет научиться принимать эти два параметра, добавлять самому модификаторы к нужным классам и в CSS компонента прописывать правила для этих модификаторов.
399 | 
400 |   Это правило внедрено после болезненного опыта поддержки проекта средней сложности, и вот какие шишки набиты с использованием примесей:
401 | 
402 |   - Нарушается инкапсуляции — использование внешних стилей внутри компоненты ведёт к проблемам в сопровождении в дальнейшем. Дело в том, что стили компоненты являются её составной частью и не должны влиять на то, что её окружает. Также справедливо обратное — внешние стили не должны влиять на компоненту. Иными словами, компонента должна быть самодостаточна. Прибегая к использованию внешних стилей, мы создаём зависимость между двумя стилями — внешним и внутренним. Каждому из стилей нужно знать, из чего состоит другой, чтобы глобальный стиль не поломал стиль компоненты. Это и есть нарушение инкапсуляции
403 | 
404 |   - Если компонента используется на 20 разных страницах, то после изменения одного свойства в самом компоненте придется пройти по всем 20 страницам вручную и проверить, что ничего не сломалось, потому что неизвестно, какие могут быть стили навешаны в местах использования через кастомные классы, и надо самому проверить все комбинации
405 | 
406 |   - Примесь обычно вешается только на верхний уровень компонента, но иногда надо кастомизировать что-нибудь внутреннее, тогда получается, надо уже две примеси передавать и принимать в компоненте, одна примесь — для свойств всего блока, вторая — для какого-то элемента, а когда понадобится еще другой элемент кастомизировать, придется добавить третью примесь :)
407 | 
408 |   - Не получится четко составить список всех возможных состояний компоненты, а при подходе с модификаторами мы явно видим все возможные параметры на входе, и когда их число будет зашкаливать, можем пнуть дизайнера, что он слишком расфантазировался и пора бы переходить к единому стайлгайду
409 | 
410 | <a name="4.6"></a>
411 | 
412 | - [4.6](#4.6) Для позиционирования блока в родительском контейнере тоже не надо использовать миксы — решается данная проблема путем добавления специальных контейнеров.
413 | 
414 |   Допустим, есть родительский блок, в нем — дочерний блок, который нам и необходимо спозиционировать. Для позиционирования внутреннего блока создаем в родительском элемент-обертку и просто задаем свойства (_margin, padding, position_ etc) этому контейнеру. Таким образом, позиционирование блока у нас находится в файле родительского блока и никак не влияет на стили самого блока.
415 | 
416 |   Данный способ позволяет, не используя миксы, спозиционировать дочерний блок.
417 | 
418 |   Например, в хэдере у нас находится обычная голубая кнопка, но именно тут, в шапке, она должна иметь отступ с левой стороны, для этого мы добавим `div.header__button`:
419 | 
420 |   ```pug
421 |   div.header
422 |     div.header__button
423 |       +button({ color:blue })
424 |   ```
425 | 
426 |   А в стили хэдера просто добавим:
427 | 
428 |   ```css
429 |   .header__button {
430 |     margin-left: 3rem;
431 |   }
432 |   ```
433 | 
434 | <a name="5"></a>
435 | 
436 | ## Возможные ошибки
437 | 
438 | > В css есть несколько очень неочевидных правил, лучше изучить их на теории заранее, чем ломать голову часами, почему верстка едет
439 | 
440 | <a name="5.1"></a>
441 | 
442 | - [5.1](#5.1) Верхний margin первого элемента смещает за собой всех родителей вниз.
443 | 
444 |   Допустим, желаемый вид должен быть таким:
445 | 
446 |   ![image](https://user-images.githubusercontent.com/12808495/55340918-d92bca80-54cf-11e9-9701-eed499af7a05.png)
447 | 
448 |   Чтобы заголовок имел отступ от верхней границы, мы добавляем ему margin: 20px 0 0; однако получаем такое поведение:
449 | 
450 |   ![image](https://user-images.githubusercontent.com/12808495/55340961-f52f6c00-54cf-11e9-8506-09894ce1988e.png)
451 | 
452 |   Несмотря на то, что маржин был поставлен только заголовку, все его родители тоже съехали вниз:
453 | 
454 |   ![image](https://user-images.githubusercontent.com/12808495/55341005-0a0bff80-54d0-11e9-8ac2-1ca16dbc40a3.png)
455 | 
456 | <a name="5.2"></a>
457 | 
458 | - [5.2](#5.2) Родители игнорируют всех детей, у которых установлены `float: left` или `float: right`
459 | 
460 | <a name="5.3"></a>
461 | 
462 | - [5.3](#5.3) `z-index` свойство работает только для элементов, у которых значение position задано как `absolute`, `fixed` или `relative`.
463 | 
464 | <a name="5.4"></a>
465 | 
466 | - [5.4](#5.4) А еще на `z-index` может повлиять `opacity` Почитать про это можно [тут](https://habrahabr.ru/post/166435/).
467 | 
468 | <a name="5.5"></a>
469 | 
470 | - [5.5](#5.5) `height` в процентах не работает, если высота родителя формируется от контента.
471 | 
472 |   На `learn.javascript.ru` даже [статья](https://learn.javascript.ru/height-percent) есть.
473 | 
474 | <a name="5.6"></a>
475 | 
476 | - [5.6](#5.6) Все `:hover` эффекты проверять на мобильных устройствах внимательно в отдельном порядке, если проект поддерживает отображения на мобилах.
477 | 
478 |   В разных браузерах ховеры ведут себя по-разному и это надо согласовывать с дизайнерами отдельно — иногда, чтобы он заработал, надо, например, отдельный тап по элементу делать. Соответственно, чтобы сработал клик, надо тапнуть два раза, что тоже для некоторых элементов будет очень странно.
479 | 
480 | <a name="5.7"></a>
481 | 
482 | - [5.7](#5.7) Псевдоэлементы (`::after/before`) [не работают](https://stackoverflow.com/questions/14585070/css-after-pseudo-element-not-showing-up-on-img/14586588#14586588) с `self-closing tags` (`<img />`, `<input />`, etc.).
483 | 
484 | <a name="5.8"></a>
485 | 
486 | - [5.8](#5.8) Не использовать простой :hover для отображения новых элементов, которые нелегко достигнуть мышкой.
487 | 
488 |   Очень часто встречаются неудачные случаи с выпадающим меню, которое реализовано через псевдо-класс `:hover`, мало того, что это меню практически неработоспособно на мобильном устройстве, оно еще и доставляет немало головной боли пользователям десктопов. Решением в данном случае будет использование JavaScript.
489 | 
490 |   ![image](https://habrastorage.org/files/45f/aa7/1eb/45faa71eb7e74d3b8c39773cd181f298.gif)
491 | 
492 | <a name="5.9"></a>
493 | 
494 | - [5.9](#5.9) В ряде браузеров (Chrome, Opera, Edge, Firefox 62-, Safari 10-) теги форм, такие как `button`, `fieldset` и `legend`, не могут стать flex-контейнерами.
495 | 
496 |   Возможное решение — использовать элемент-обертку внутри тега (например, `span class="button__text"` внутри кнопки), и уже для него указать свойство `display: flex`:
497 | 
498 |   ```html
499 |   <button class="button">
500 |     <span class="button__text">...</span>
501 |   </button>
502 |   ```
503 | 
504 |   ```css
505 |   .button__text {
506 |     display: flex;
507 |     ...;
508 |   }
509 |   ```
510 | 
511 |   Подробнее об этом и других багах, возникающих при работе с флексами, можно прочитать на [Flexbugs](https://github.com/philipwalton/flexbugs), перевод материала на русский [здесь](https://css-live.ru/articles/brauzernye-bagi-flexbox.html).
512 | 
513 |   Для решения проблем с флексами можно воспользоваться неплохим [postcss-плагином](https://github.com/luisrudge/postcss-flexbugs-fixes), который автоматически фиксит некоторые баги в написании стилей для флексов.
514 | 


--------------------------------------------------------------------------------
/Environment/README.md:
--------------------------------------------------------------------------------
 1 | # Окружение
 2 | 
 3 | Помимо написания кода и реализации функционала, нам, программистам, необходимо думать и о других вещах. О качестве и читаемости написанного кода, о написании кода в едином стиле, о создании качественной git истории и о многом другом. 
 4 | 
 5 | К счастью для нас, есть множество инструментов, которые нам в этом помогают. Именно о таких инструментах пойдёт речь в этом разделе.
 6 | 
 7 | 1. [Git hooks with husky](./husky.md)
 8 | 2. [Lint-staged](./lint-staged.md)
 9 | 3. [Conventional Commits](./conventional-commits.md)
10 | 4. [Branches &  Pull Requests](./branches-and-requests.md)


--------------------------------------------------------------------------------
/Environment/branches-and-requests.md:
--------------------------------------------------------------------------------
 1 | # Branches и Pull Requests
 2 | 
 3 | Здесь можно найти небольшой свод правил и возможностей по именованию веток и ведению Pull Requests (или Merge Requests в GitLab). 
 4 | 
 5 | ## Branches
 6 | 
 7 | Существует [множество](https://byurrer.ru/git-workflow) подходов к именованию и организации веток - GitFlow, GitHub flow, GitLab flow и др. Выберете вы один из этих или будете использовать свой, зависит от требований вашего проекта и от того, как вы договоритесь с командой.
 8 | 
 9 | Вот простой вариант который можно использовать на проекте:
10 | 
11 | - `main` (или `master`) - в этой ветке содержится самая стабильная версия вашего проекта, которая как правило используется для деплоя в production (хотя для этого может быть отдельная ветка `prod`). 
12 | - `dev` - ветка разработки. В ней содержатся последние готовые фичи, добавленные в ваш проект. Ветка может быть развёрнута на стейдж для полной проверки функционала перед слиянием в `main` и деплоем в production.
13 | - Ветки с новым функционалом или любой другой задачей из инструмента по трекингу задач ответвляются от `dev` и именуются `issueNumber-short-task-description`.
14 | 
15 | **Минимальная рекомендация** - если у вас на проекте есть трекинг задач (GitHub/GitLab issues, Jira и др), ветка должна именоваться в формате `label-issueNumber-short-task-description`, например: `feature-234-add-product-card`. Вы можете использовать лейблы из вашей системы трекинга задач. Если таковых не имеется, вот примеры для `label`: `feature, fix, docs, refactor, test, build, perf`. Если у вас на проекте нет трекинга задач, название ветки должно отражать суть ваших изменений. Название должно быть коротким и в тоже время понятным. 
16 | 
17 | ## Pull Requests
18 | 
19 | Вы можете связать ваш Pull Request с одним или несколькими issues, которых он касается, используя синтаксис `#issueNumber` в описании Pull Request, например: `#234 #235`. 
20 | 
21 | Вы также можете сделать так, что бы issue автоматически закрылся после слияния ветки, добавив в описание Pull Request слово `closes` перед номером issue, например: `closes #234, closes #235`.
22 | 
23 | Вы можете упомянуть какого-то человека в описании или комментариях Pull Request, используя синтаксис `@username`.
24 | 
25 | Если ваш Pull Request содержит незаконченную задачу и не готов к слиянию, вы можете пометить его как `Draft` во время или после создания Pull Request. Интерфейс будет зависеть от того, где вы работаете, в GitHub или GitLab. Pull Request нельзя слить пока активна метка `Draft`.


--------------------------------------------------------------------------------
/Environment/conventional-commits.md:
--------------------------------------------------------------------------------
  1 | # Соглашение о коммитах
  2 | 
  3 | Мы пишем коммиты в соответствии с [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) ([RU](https://www.conventionalcommits.org/ru/v1.0.0/)). В этом топике будет гайд о том, как использовать `Conventional Commits` в вашем проекте. 
  4 | 
  5 | Помимо Conventional Commits в сообществе есть несколько устоявшихся правил, которых мы придерживаемся:
  6 | 
  7 | - Не использовать прошедшее время. То есть вместо `added` будет `add`, вместо `updated` будет `update` и так далее.
  8 | - Текст коммитов писать в `lower case`. Например: `feat: add transaction component`, `fix: translation`.
  9 | 
 10 | <details>
 11 | <summary>Содержание</summary>
 12 | 
 13 |  - [Зачем использовать соглашение о коммитах?](#зачем-использовать-соглашение-о-коммитах)
 14 |  - [Prerequisites](#prerequisites)
 15 |  - [Установка](#установка)
 16 |  - [Использование](#использование)
 17 |  - [Конфигурация](#конфигурация)
 18 |  - [[Опционально] Commitizen](#commitizen)
 19 |  
 20 | </details>
 21 | 
 22 | ## Зачем использовать соглашение о коммитах?
 23 | 
 24 | - Позволяет проще ориентироваться в истории Git как участникам проекта, так и новичкам.
 25 | - Стимулирует делать более осмысленные и более качественные коммиты. Простые сообщения `fix` или `update` не подойдут.
 26 | - Стимулирует делать коммиты меньших размеров благодаря ограничениям по типу (type) и контексту (scope) коммита.
 27 | - Conventional Commits полностью совместимо с [семантическим версионированием](https://semver.org/) ([RU](https://semver.org/lang/ru/)). А это значит, что вы можете использовать множество инструментов для автоматической генерации CHANGELOG и выпуска релизов. Если однажды вам придётся разрабатывать и/или поддерживать какой-либо npm пакет, вам не придётся заново учиться писать коммиты.
 28 | 
 29 | К сожалению даже с Conventional Commits чисто технически можно делать большие коммиты и писать непонятные текста коммитов. Но коллеги вам за это спасибо не скажут, а будущий "вы" будете ругать себя при попытке найти коммит с очередным багом. Соглашение о коммитах стимулирует и помогает думать в правильном направлении при оформлении коммитов.
 30 | 
 31 | ## Prerequisites
 32 | 
 33 | Прежде чем переходить к установке, прочтите официальную документацию [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) ([RU](https://www.conventionalcommits.org/ru/v1.0.0/)) и убедитесь, что вы установили [husky](./husky.md).
 34 | 
 35 | ## Установка
 36 | 
 37 | Мы будем использовать `husky` и `commitlint` ([документация](https://commitlint.js.org/#/)). 
 38 | 
 39 | 1. Установите следующие пакеты в качестве devDependencies используя ваш пакетный менеджер, например:
 40 | 
 41 |     `npm install --save-dev @commitlint/config-conventional @commitlint/cli`
 42 | 
 43 | 2. Создайте в корне проекта файл `commitlint.config.js` со следующим содержимым:
 44 | 
 45 |     ```js
 46 |     module.exports = {
 47 |       extends: ['@commitlint/config-conventional'],
 48 |       rules: {
 49 |         'subject-case': [2, 'always', ['lower-case']],
 50 |       }
 51 |     };
 52 |     ```
 53 | 
 54 | 3. Добавьте скрипт в ваш `package.json`:
 55 | 
 56 |     ```json
 57 |     {
 58 |       "scripts": {
 59 |         "commitlint": "commitlint --edit"
 60 |       }
 61 |     }
 62 |     ```
 63 | 4. Создайте файл `.husky/commit-msg` со следующим содержимым: 
 64 | 
 65 |     ```shell
 66 |     #!/usr/bin/env sh
 67 |     . "$(dirname -- "$0")/_/husky.sh"
 68 | 
 69 |     npm run commitlint 
 70 |     # pnpm run commitlint <- if you're using pnpm
 71 |     # yarn commitlint <- if you're using yarn
 72 |     ```
 73 | 
 74 | Ура! Теперь сообщения ваших коммитов будут проверяться на соответствие Conventional Commits.
 75 | 
 76 | ## Использование
 77 | 
 78 | По умолчанию в `@commitlint/config-conventional` доступны следующие типы коммитов: 
 79 | 
 80 | - **feat:** Новый функционал.
 81 | - **fix:** Фикс бага.
 82 | - **docs:** Изменения документации.
 83 | - **style:** Изменения, не затрагивающие поведение кода - (отступы, форматирование, кавычки и др.). Не путать с изменениями CSS стилей.
 84 | - **refactor:** Изменение кода, которое не исправляет ошибку и не добавляет новый функционал.
 85 | - **perf:** Изменение кода, улучшающее производительность.
 86 | - **test:** Добавление тестов или исправление существующих.
 87 | - **build:** Изменения, влиюящие на систему сборки или внешние зависимости.
 88 | - **ci:** Изменения файлов и скриптов CI. 
 89 | - **chore:** Другие изменения не меняющие исходные или тестовые файлы.
 90 | - **revert:** Отмена предыдущего коммита.
 91 | 
 92 | Вы можете пользоваться этим как шпаргалкой, но через пару недель активного использования вам это не понадобится :).
 93 | 
 94 | Один из возможных вариантов использования `scope` - в нём можно указывать путь к добавляемому/изменяемому модулю, например `feat(some-path/to/module): some-changes-description`. Это может существенно облегчить поиск по коммитам. В случаях, когда нет однозначного пути, его можно опустить.
 95 | 
 96 | ## Конфигурация
 97 | 
 98 | Вы так же можете расширить базовый конфиг, например, добавив новые типы коммитов. Для этого переопределите правила в объекте `rules` файла `commitlint.config.js`:
 99 | 
100 | ```js
101 | module.exports = {
102 |   // Включение базового конфига
103 |   extends: ['@commitlint/config-conventional'],
104 |   rules: {
105 |     // ваши правила
106 |   },
107 | };
108 | ```
109 | 
110 | Подробнее о самих правилах можно почитать [здесь](https://commitlint.js.org/#/reference-rules).
111 | 
112 | ## Commitizen (опционально)
113 | 
114 | Commitizen - это инструмент, позволяющий создавать коммиты в соответствии с `Conventional Commits` в формате вопрос-ответ. Это необязательно, но возможно кому-то он понравится. Сначала в командной строке вас попросят выбрать тип коммита, затем его контекст (scope), затем его описание и так далее. Commitizen сам создаст коммит в правильном формате. 
115 | 
116 | ![1](https://raw.githubusercontent.com/commitizen/cz-cli/master/meta/screenshots/add-commit.png)
117 | 
118 | Изначально, `commitizen` это самостоятельный инструмент, никак не связанный с `commitlint`. Но у `commitlint` есть адаптер, который позволяет запускать `commitizen`, который будет следовать конфигурации `commitlint.config.js`. 
119 | 
120 | ### Установка
121 | 
122 | 1. Установите следующие пакеты в качестве devDependencies используя ваш пакетный менеджер, например:
123 | 
124 |     `npm install --save-dev @commitlint/cz-commitlint commitizen`
125 | 
126 | 2. Добавьте следующие строчки в ваш `package.json`:
127 | 
128 |     ```json
129 |     {
130 |       "scripts": {
131 |         "commit": "cz"
132 |       },
133 |       "config": {
134 |         "commitizen": {
135 |           "path": "@commitlint/cz-commitlint"
136 |         }
137 |       }
138 |     }
139 |     ```
140 | 
141 | ### Использование
142 | 
143 | Просто вызовите скрипт `commit` используя ваш пакетный менеджер, например: `npm run commit`. И всё!


--------------------------------------------------------------------------------
/Environment/husky.md:
--------------------------------------------------------------------------------
 1 | # Git hooks with husky
 2 | 
 3 | Этот топик является предварительным условиям для некоторых инструментов из раздела **Окружение**. Здесь вкратце рассказывается о том, что такое `git hooks`, `husky` и как установить `husky` в ваш проект.
 4 | 
 5 | ## Что такое `git hooks`?
 6 | 
 7 | Хуки Git - это встроенный функционал Git, который позволяет вызывать пользовательские скрипты в случае возникновения определённых Git-событий. Например хук `pre-commit` будет вызван после вызова команды `git commit`, но перед фактическим созданием коммита. В этом хуке можно запустить тесты, линтеры или выполнить любую другую проверку кода. Если выполнение хука завершится с кодом, отличным от нуля, создание коммита будет отменено. Или хук `commit-msg` позволяет проверить сообщение коммита на соответствие заданному шаблону. Подробнее о хуках Git можно почитать в [официальной документации](https://git-scm.com/book/ru/v2/%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0-Git-%D0%A5%D1%83%D0%BA%D0%B8-%D0%B2-Git).
 8 | 
 9 | ## Что такое `husky`?
10 | 
11 | [Husky](https://typicode.github.io/husky/) — это инструмент, который позволяет нам легко использовать хуки Git и запускать нужные нам сценарии на разных событиях. Для этого достаточно добавить скрипт в файл `.husky/[название-хука]` вашего проекта.
12 | 
13 | ### Установка
14 | 
15 | 1. Используя ваш пакетный менеджер установите husky в качестве devDependency, 
16 | например: 
17 |     
18 |     `npm install husky --save-dev`
19 | 
20 | 2. Активируйте хуки Git от `husky` выполнив команду:
21 | 
22 |     `npx husky install`
23 | 
24 |     После активации в корне вашего проекта появится папка `.husky`, внутри которой вы можете добавлять свои скрипты для разных [Git событий](https://git-scm.com/book/ru/v2/%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0-Git-%D0%A5%D1%83%D0%BA%D0%B8-%D0%B2-Git). Эта папка будет использоваться для некоторых инструментов из раздела [Окружение](../Environment/README.md).
25 | 
26 |     Эту команду необходимо будет выполнять после скачивания репозитория и установки зависимостей, так что рекомендуем добавить это в `README` вашего проекта, что бы ваши коллеги были в курсе использования `husky`. Ниже описан способ автоматической активации хуков Git после установки зависимостей.
27 | 
28 | ### Опционально 
29 | 
30 | 1. Для автоматической активации хуков Git после установки зависимостей добавьте в ваш `package.json` следующую строчку:
31 | 
32 |     ```json
33 |     {
34 |       "scripts": {
35 |         "prepare": "husky install" 
36 |       }
37 |     }
38 |     ```
39 |     Скрипт `prepare` является [скриптом жизненного цикла](https://docs.npmjs.com/cli/v10/using-npm/scripts#life-cycle-scripts), который будет выполняться после каждой установки зависимостей. 
40 | 
41 |     Будьте осторожны, такое поведение может привести к проблемам в некоторых тестовых/продакшен серверах. Если вы столкнулись с такими проблемами, лучше использовать ручную активацию.
42 | 
43 |     Если вы используете Yarn 2+, замените `prepare` на `postinstall`.
44 | 
45 | 
46 | 4. Если вы используете Yarn 2+, ваш репозиторий публичный и вы публикуете его в реестре (напр. **npmjs.com**), вам необходимо установить `yarn add pinst --dev` и добавить в `package.json` следующее:
47 | 
48 |     ```json
49 |     {
50 |       "scripts": {
51 |         "postinstall": "husky install",
52 |         "prepack": "pinst --disable",
53 |         "postpack": "pinst --enable"
54 |       }
55 |     }
56 |     ```
57 |     Подробнее в [документации](https://typicode.github.io/husky/getting-started.html#yarn-2).
58 | 
59 | 


--------------------------------------------------------------------------------
/Environment/lint-staged.md:
--------------------------------------------------------------------------------
 1 | # Lint-staged
 2 | 
 3 | [Lint-staged](https://github.com/lint-staged/lint-staged) - это небольшая утилита, которая позволяют запускать набор команд для файлов, которые были проиндексированы Git (добавлены с помощью `git add`). Нам это полезно тем, что мы можем настроить Git hooks и перед каждым коммитом запускать линтеры только для проиндексированных файлов.
 4 | 
 5 | ## Prerequisites
 6 | 
 7 | Прежде чем переходить к установке, убедитесь, что вы установили [husky](./husky.md).
 8 | 
 9 | ## Установка
10 | 
11 | 1. Установите `lint-staged` в качестве devDependencies используя ваш пакетный менеджер, например:
12 | 
13 |     `npm install --save-dev lint-staged`
14 | 
15 | 2. Создайте в корне проекта файл `.lintstagedrc` со следующим содержимым:
16 | 
17 |     ```json
18 |     {
19 |       "*.{css}": "stylelint --fix",
20 |       "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
21 |       "*.{md,json}": "prettier --write"
22 |     }
23 |     ```
24 |     Файл конфигурации может зависеть от особенностей вашего проекта. Подробнее [здесь](https://github.com/lint-staged/lint-staged#configuration).
25 | 
26 | 3. Добавьте скрипт в ваш `package.json`:
27 | 
28 |     ```json
29 |     {
30 |       "scripts": {
31 |         "lint-staged": "lint-staged"
32 |       }
33 |     }
34 |     ```
35 | 4. Создайте файл `.husky/pre-commit` со следующим содержимым: 
36 | 
37 |     ```shell
38 |     #!/usr/bin/env sh
39 |     . "$(dirname -- "$0")/_/husky.sh"
40 | 
41 |     npm run lint-staged 
42 |     # pnpm run lint-staged <- if you're using pnpm
43 |     # yarn lint-staged <- if you're using yarn
44 |     ```
45 | 
46 | ## Использование
47 | 
48 | Просто делайте коммиты как обычно. Вышеупомянутый конфиг будет запускать скрипты линтеров с автоматическим исправлением для индексированных файлов. Если какой-то скрипт завершится с ошибкой, создание коммита будет отменено. 


--------------------------------------------------------------------------------
/HTML/README.md:
--------------------------------------------------------------------------------
  1 | # HTML
  2 | 
  3 | 1. [Семантика](#1)
  4 | 2. [Теги](#2)
  5 | 3. [Подключаемые файлы](#3)
  6 | 
  7 | <a name="1"></a>
  8 | 
  9 | ## Семантика
 10 | 
 11 | <a name="1.1"></a>
 12 | 
 13 | - [1.1](#1.1) Объединять блоки не по их визуальному расположению, а по их смыслу.
 14 | 
 15 |   Объединяем блоки вот так:  
 16 |   ![хороший пример](https://github.com/fullstack-development/developers-roadmap/assets/90761929/db6e1f7c-59d9-41dd-8334-ca96d7a07049)
 17 | 
 18 |   А не вот так:  
 19 |   ![плохой пример](https://github.com/fullstack-development/developers-roadmap/assets/90761929/16982193-66b0-447e-bf32-3956f2f3a584)
 20 |   Как минимум, это очень легко позволит потом добавить новый элемент, когда надо будет по требованию заказчика сделать лист из 4 элементов, а не трех, как здесь. Плюс второй подход очень неудобен, если контент генерируется динамически. Так что если вы создаете верстку, которую потом будут прикручивать к бэкенду заказчики, и сделаете такую верстку, проклятия от их программистов и порча всей нашей кармы обеспечены.
 21 | 
 22 | <a name="1.2"></a>
 23 | 
 24 | - [1.2](#1.2) Если есть что-то похожее на список, проверяем, как будет выглядеть при большем количестве элементов.
 25 | 
 26 |   ![список](https://rizzoma.com/r/files/a87a0a28b84d6326d4f3909e8801dab7-97a135d68ad6e2e449e9c9f2dbf9766c-0-0.6276249218551724)
 27 | 
 28 |   Если непонятно, что будет при 4-х элементах, как в этом случае, обязательно спросить, а не принимать решение самостоятельно
 29 | 
 30 | <a name="1.3"></a>
 31 | 
 32 | - [1.3](#1.3) Все элементы с текстом, контент которых формируется динамически, проверяем на то, чтобы они не ломались при большем количестве текста, чем на макете.
 33 | 
 34 |   В имена подставляем знаменитое [Константин Константинопольский](https://tema.livejournal.com/1322108.html).  
 35 |   В идеале моменты, которые будет трудно масштабировать текстом, находить еще на стадии знакомства с макетом и задавать вопросы дизайнеру.
 36 | 
 37 | <a name="1.4"></a>
 38 | 
 39 | - [1.4](#1.4) Проверять страницы на наличие ошибок [W3C валидатором](https://validator.w3.org/#validate_by_uri). Если требуется прогонять страницы локально, воспользоваться [расширением для браузера](https://chrispederick.com/work/web-developer/). Предупреждения можно устранять по мере необходимости, исходя из условий проекта.
 40 | 
 41 |   Часто встречающиеся ошибки:
 42 | 
 43 |   <a name="1.4.1"></a>
 44 | 
 45 |   - [1.4.1](#1.4.1) Вставка блочных элементов внутрь инлайновых.
 46 | 
 47 |     Никаких `<span><div></div></span>`.
 48 | 
 49 |   <a name="1.4.2"></a>
 50 | 
 51 |   - [1.4.2](#1.4.2) Не предназначенные для расширения другими файлами через какой-нибудь шаблонизатор .html файлы страниц начинаются не с `<!DOCTYPE html>`, что противоречит HTML5 стандарту.
 52 | 
 53 |   <a name="1.4.3"></a>
 54 | 
 55 |   - [1.4.3](#1.4.3) Используются самозакрывающиеся теги, если они поддерживают другой режим.
 56 | 
 57 |     Нельзя:
 58 | 
 59 |     ```html
 60 |     <div />
 61 |     <span />
 62 |     ```
 63 | 
 64 |     Можно:
 65 | 
 66 |     ```html
 67 |     <link />
 68 |     <img />
 69 |     <input />
 70 |     ```
 71 | 
 72 |   <a name="1.4.4"></a>
 73 | 
 74 |   - [1.4.4](#1.4.4) Не все изображения `<img>` содержат `alt` атрибут.
 75 | 
 76 |   <a name="1.4.5"></a>
 77 | 
 78 |   - [1.4.5](#1.4.5) Есть вложенные формы `<form>`.
 79 | 
 80 |   Полный список потенциальных ошибок описан [тут](https://validator.w3.org/docs/errors.html).
 81 | 
 82 | <a name="1.5"></a>
 83 | 
 84 | - [1.5](#1.5) Использовать h1..h6 только для заголовков, причем h1 должен встречаться в одной странице всего один раз.
 85 | 
 86 | <a name="1.6"></a>
 87 | 
 88 | - [1.6](#1.6) Использовать `<table>` только для реальных таблиц.
 89 | 
 90 |   Если перед таблицей есть её текстовое описание, сделать это внутри тега `<table>` через `<caption>`.  
 91 |   Если у таблицы первая строка идет заголовком, то использовать `<thead>` и вложенные `<th>` для этого и использовать "scope" для этих ячеек.
 92 | 
 93 |   Пример:
 94 | 
 95 |   ```html
 96 |   <table>
 97 |     <caption>
 98 |       First two U.S. presidents
 99 |     </caption>
100 |     <thead>
101 |       <tr>
102 |         <th scope="col">Name</th>
103 |         <th scope="col">Took office</th>
104 |         <th scope="col">Party</th>
105 |       </tr>
106 |     </thead>
107 |     <tbody>
108 |       <tr>
109 |         <td>George Washington</td>
110 |         <td>April 30, 1789</td>
111 |         <td>n/a</td>
112 |       </tr>
113 |       <tr>
114 |         <td>John Adams</td>
115 |         <td>March 4, 1797</td>
116 |         <td>Federalist</td>
117 |       </tr>
118 |     </tbody>
119 |   </table>
120 |   ```
121 | 
122 | <a name="1.7"></a>
123 | 
124 | - [1.7](#1.7) Не использовать `<br>` нигде, кроме случаев, когда соблюдены все требования:
125 | 
126 |   - Newlines are semantically meaningful.
127 |   - Indentation is not semantically meaningful (otherwise you should use a `<pre>`).
128 |   - There exists no other semantically appropriate tag, like a paragraph or header tag.
129 | 
130 | <a name="1.8"></a>
131 | 
132 | - [1.8](#1.8) Использовать семантические теги.
133 | 
134 |   Почему их нужно использовать, узнать можно [здесь](https://www.youtube.com/watch?v=bDYEnNzprzE) и [здесь](https://developer.mozilla.org/ru/docs/Learn/%D0%94%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D0%BE%D1%81%D1%82%D1%8C/HTML).  
135 |   [Блок-схема](http://html5doctor.com/downloads/h5d-sectioning-flowchart.pdf) для выбора семантических тегов.
136 | 
137 | <a name="2"></a>
138 | 
139 | ## Теги
140 | 
141 | <a name="2.1"></a>
142 | 
143 | - [2.1](#2.1) Все теги должны работать даже без CSS и JS.
144 | 
145 |   Все тексты, видимые сначала при открытии страницы так же должны быть доступны, формы должны сабмититься, ссылки должны переходить (а ссылки, по которым вообще не должно быть перехода и для которых принято ставить `href="#"`, вообще не использовать, это будет далее).
146 | 
147 | <a name="2.2"></a>
148 | 
149 | - [2.2](#2.2) Структура тегов в первую очередь должна идти от содержания, а не от дизайна
150 | 
151 |   ![пример](http://image.prntscr.com/image/a89c1aed00f14864851989caceacd59d.png) — например, такой элемент можно оформить как четыре идущих подряд элемента: иконка сообщений, бадж с цифрой 10, иконка аватара и имя пользователя. Но тут надо явно объединить с помощью `<div>` два блока, чтобы семантически они были отдельными — блок с информацией по сообщению и блок про пользователя. Для css потом, возможно, придется писать лишние стили, но верстка будет более осмысленной и не привязанной лишний раз к дизайну.
152 | 
153 | <a name="2.3"></a>
154 | 
155 | - [2.3](#2.3) Перед `<!DOCTYPE html>` не должно быть никаких символов, включая пробелы и переносы строк.
156 | 
157 | <a name="2.4"></a>
158 | 
159 | - [2.4](#2.4) Внутри `<head>` первым тегом должно идти `<meta charset="utf-8">`.
160 | 
161 | <a name="2.5"></a>
162 | 
163 | - [2.5](#2.5) У каждой страницы должны быть теги `title` и мета теги `keywords`, `description` (на содержимое спросить контент у менеджера).
164 | 
165 | <a name="2.6"></a>
166 | 
167 | - [2.6](#2.6) В `head` добавлять `<meta name="viewport" content="initial-scale=1.0, width=device-width">` — на мобильных браузерах можно избежать горизонтального скролла и масштабировать контент на всю ширину экрана.
168 | 
169 | <a name="2.7"></a>
170 | 
171 | - [2.7](#2.7) Все атрибуты должны быть внутри двойных кавычек
172 | 
173 |   Нельзя:
174 | 
175 |   ```html
176 |   <img width=200 />
177 |   <div class=block>
178 |     <a href='/some/url'></a>
179 |   </div>
180 |   ```
181 | 
182 |   Можно:
183 | 
184 |   ```html
185 |   <img width="200" />
186 |   <div class="block">
187 |     <a href="/some/url"></a>
188 |   </div>
189 |   ```
190 | 
191 |   Плюс, если в проекте нет других соглашений, атрибуты должны именоваться lower-case-hyphenated (имена только маленькими буквами и через дефис) и, если значение строковое и показывает какое-то имя, то тоже должно быть lower-case-hyphenated. Кастомные атрибуты стараться начинать с data- (это стандартная практика, рекомендованная для HTML5).
192 | 
193 |   Пример: `<a href="/" data-index="33" data-page-name="main-page">Home</a>`
194 | 
195 | <a name="2.8"></a>
196 | 
197 | - [2.8](#2.8) Не использовать id, кроме случаев, когда они семантически востребованы.
198 | 
199 |   Когда гарантируется их уникальность, например, на уровне базы данных и когда вам нужно:
200 | 
201 |   - сделать рабочую навигацию в рамках одной страницы (например, как на Википедии или на этом сайте сборника [best-practices](https://isobar-idev.github.io/code-standards/#javascript_javascript).
202 |   - связать `<label>` и `<input />`, которые находятся в совершенно разных ветках дерева DOM (вообще, лучше всегда просто `<input />` внутрь `<label>` ставить, и тогда никакие айдишники не нужны).
203 | 
204 | <a name="2.9"></a>
205 | 
206 | - [2.9](#2.9) Все теги идут только с классами — никаких пустых `<div>`, `<section>` и т. д. Но можно для инлайновых элементов, если есть четкое понимание зачем. Это очень сильно мешает новым людям входить в проект и вам через некоторое время разобраться в собственной верстке.
207 | 
208 | <a name="2.10"></a>
209 | 
210 | - [2.10](#2.10) Избегать по максимуму инлайновые стили и обработчики событий в `html` (то есть никаких `<div onclick="func()">`).
211 | 
212 | <a name="2.11"></a>
213 | 
214 | - [2.11](#2.11) Не использовать ссылки с пустым или невалидным `href` (никаких `<a href="#">`) — тогда лучше использовать ссылку-заглушку на несуществующий урл, который явно говорит, что ссылка не проставлена.
215 | 
216 |   Если вы верстаете проект, в котором есть страницы, которых нет в дизайне (допустим, они потом при интеграции с сервером динамически создаваться будут), то лучше ставьте адрес, который явно говорит, что это ссылка-заглушка. Причем все ссылки-заглушки должны в рамках проекта иметь один адрес, например `<a href="/mock-address/change-me"></a>`.  
217 |   Для SPA иногда приходится динамически js-ом генерить такие ссылки (как минимум в angular, там для этого даже отдельный атрибут ng-href), которые бы поддерживали динамическую генерацию на основе чистого клиентского раутинга.  
218 |   Не надо никаких `<a href="#">` или `<a href="javascript:someFunc(1)">`. Плюс не надо сюда сохранять урлы до методов API на сервере, надеясь, что JS-ом вы сможете потом обработать клик, отправить ajax запрос на сервер по этому урлу и сами обработать ответ. Этого не произойдет, если юзер откроет ссылку в новой вкладке через контекстное меню или клик колесом мыши, например. Все урлы, указанные в `href`, должны открывать читаемый для человека контент, который целиком зависит только от сервера. [Оригинал последнего абзаца](https://isobar-idev.github.io/code-standards/#html_anchors_amp_links).
219 | 
220 | <a name="2.12"></a>
221 | 
222 | - [2.12](#2.12) Ссылки на чужие сайты должны содержать атрибут `target="_blank"`, чтобы открываться в новом окне.
223 | 
224 | <a name="2.13"></a>
225 | 
226 | - [2.13](#2.13) Все ссылки с `target="_blank"` должны так же содержать атрибут `rel="noreferrer"`.
227 | 
228 |   Это связано с [уязвимостью](https://mathiasbynens.github.io/rel-noopener/), в соответствии с которой сайт, который вы открыли, получит доступ к сайту, с которого перешли через `window.opener`, причем это работает даже кроссдоменно.
229 | 
230 | <a name="2.14"></a>
231 | 
232 | - [2.14](#2.14) Все инпуты, селекты и другие интерактивные элементы форм должны располагаться внутри тега `<form>`.
233 | 
234 |   ```html
235 |   <form>
236 |     <label>
237 |       First name:
238 |       <input type="text" name="first-name" value="John" />
239 |     </label>
240 |     <label>
241 |       Last name:
242 |       <input type="text" name="last-name" value="Doe" />
243 |     </label>
244 |     <button type="submit">Submit</button>
245 |   </form>
246 |   ```
247 | 
248 | <a name="2.15"></a>
249 | 
250 | - [2.15](#2.15) Все интерактивные элементы, для которых дизайнером задуман нетривиальный порядок полей, должны иметь атрибут `tabindex`, плюс всегда кнопка сабмита в tabindex должна быть последней (соответственно, если есть визуально поля под кнопкой, у них должен быть tabindex и он должен быть меньше, чем у кнопки).
251 | 
252 | <a name="2.16"></a>
253 | 
254 | - [2.16](#2.16) Спрашивать у дизайнеров, какие элементы делать autofocus на какой странице.
255 | 
256 | <a name="2.17"></a>
257 | 
258 | - [2.17](#2.17) Если у поля есть четкое назначение, то использовать соответствующий тип (email, number, color и т. д.).
259 | 
260 | <a name="2.18"></a>
261 | 
262 | - [2.18](#2.18) Каждый тег, в котором может лежать текст, должен быть проверен на большое количество символов.
263 | 
264 |   Все заголовки и все теги с текстовыми описаниями.  
265 |   Все инпуты проверять, чтобы при заполнении текст не прижимался вплотную к правой границе:  
266 |   ![image](https://user-images.githubusercontent.com/12808495/55307777-c0e18e80-5482-11e9-927f-9c195d81555e.png)
267 | 
268 | <a name="2.19"></a>
269 | 
270 | - [2.19](#2.19) Классические инлайн теги должны быть только inline или inline-block, и в них не должно быть ничего, кроме простого текста и других таких же инлайновых тегов.
271 | 
272 |   Исключения: `<a>` — иногда ссылку надо сделать блочным элементом, но лучше использовать inline-block.
273 | 
274 | <a name="2.20"></a>
275 | 
276 | - [2.20](#2.20) Для телефонов, емайл-адресов и скайп никнеймов нужно использовать `<a>` c соответствующим адресом.
277 | 
278 |   ```html
279 |   <a href="tel: +74951234567">+7 (495) 123-45-67</a>
280 |   <a href="mailto: example@mail.ru">example@mail.ru</a>
281 |   <a href="skype: someskype?call">someskype</a>
282 |   ```
283 | 
284 | <a name="2.21"></a>
285 | 
286 | - [2.21](#2.21) Отображать примеры кода через тег `<code>`.
287 | 
288 |   Иногда на некоторых проектах нужно прямо на сайте показывать пользователям примеры кода (например, [здесь в туториале Реакта](https://reactjs.org/) целая куча примеров кода) — эти примеры должны быть написаны моноширинными шрифтами и отличаться от обычного текста — по умолчанию достаточно обрамить код в тeг `<code>`.
289 | 
290 | <a name="3"></a>
291 | 
292 | ## Подключаемые файлы
293 | 
294 | <a name="3.1"></a>
295 | 
296 | - [3.1](#3.1) Все картинки, шрифты и т. д. должны иметь уникальное название в рамках проекта и не содержать кириллических символов. Если в проекте нет индивидуальных соглашений, то они должны именоваться в стиле lower-case-hyphenated.
297 | 
298 | <a name="3.2"></a>
299 | 
300 | - [3.2](#3.2) В проекте обязательно должен быть favicon.ico, подключаемый на всех страницах.
301 | 
302 |   Как это сделать, используя webpack, очень хорошо написано в [этой статье](https://medium.com/tech-angels-publications/bundle-your-favicons-with-webpack-b69d834b2f53).
303 | 
304 | <a name="3.3"></a>
305 | 
306 | - [3.3](#3.3) В сафари своя версия favicon, ее тоже обязательно надо настраивать.
307 | 
308 |   То есть нужна svg для контура иконки, и нужен цвет для иконки при наведении. [Статья](https://yoast.com/dev-blog/safari-pinned-tab-icon-mask-icon/).
309 | 
310 | <a name="3.4"></a>
311 | 
312 | - [3.4](#3.4) Прогонять картинки через [kraken.io](https://kraken.io/) или использовать свои CLI-утилиты для этого.
313 | 
314 | <a name="3.5"></a>
315 | 
316 | - [3.5](#3.5) Все фотографии и картинки, где нет прозрачности, делать в jpg.
317 | 
318 | <a name="3.6"></a>
319 | 
320 | - [3.6](#3.6) При нарезке картинок из фотошопа поставить DPI равным 72dpi, а саму картинку сохранить через "Save for Web".
321 | 
322 | <a name="3.7"></a>
323 | 
324 | - [3.7](#3.7) Максимальная ширина картинки — 1920 пикселей. Если в макетах она больше, пропорционально ужимайте.
325 | 
326 |   На самом деле, это правило спорно (как минимум для ретина дисплеев я не уверен), но следуйте ему, пока дизайнер не скажет другого.
327 | 


--------------------------------------------------------------------------------
/Initiation.md:
--------------------------------------------------------------------------------
 1 | # Инициация
 2 | 
 3 | <a name="1"></a>
 4 | 
 5 | - [1](#1) Создать README.md.
 6 | 
 7 |   - У каждого проекта, размещенного на github, должно быть readme.md.
 8 | 
 9 |   - Readme должно содержать название проекта.
10 | 
11 |   - Readme должно содержать всю необходимую информацию для развертывания (установки) проекта и запуска/тестирования, обязательно самим протестировать с нуля разворачивание в новой папке.
12 | 
13 |   - В проекте должно быть использовано по минимуму глобальных библиотек, все они должны быть перечислены в Readme (webpack, karma и все, что может быть поставлено через npm, точно не должно быть глобальным).
14 | 
15 |   - Если из названия проекта не ясно его предназначение, то стоит внести его краткое описание.
16 | 
17 |   - Если в проекте используются нестандартные библиотеки или архитектурные подходы, то их тоже нужно указывать. Причем желательно указывать ссылки на их репозитории, чтобы человеку поставленному на этот проект, но не работавшему с используемыми технологиями, не нужно было искать их в гугле.
18 | 
19 |   - Если проект из репозитория уже где-то развернут (например, на github pages), то следует указать на него ссылку.
20 | 
21 | <a name="2"></a>
22 | 
23 | - [2](#2) Отступы делать пробелами, на проекте во всех файлах html, pug, etc должен быть одинаковый отступ — либо 4, либо 2 пробела.
24 | 
25 | <a name="3"></a>
26 | 
27 | - [3](#3) Спросить на входе, под какие браузеры верстаем (обязательно).
28 | 
29 | <a name="4"></a>
30 | 
31 | - [4](#4) Спросить, есть ли адаптив, если нет — то под какие разрешения верстать и что делать для других экранов.
32 | 
33 | <a name="5"></a>
34 | 
35 | - [5](#5) Запускать сайт через http://localhost, а не через file:///c:\test.html
36 | 
37 |   Иначе могут быть проблемы с элементами, вставляемыми через iframe (например, лайки от фб, вк и т. д.), и при работе скриптов, которые отправляют HTTP-запросы, плюс еще могут быть вообще неожиданные и неизвестные нам проблемы.
38 | 
39 | <a name="6"></a>
40 | 
41 | - [6](#6) Заранее четко узнать, что является фиксированным результатом проекта — развернутое на нашем сервере production-окружение или только git-репозиторий, а то и zip-архив, отправленный по почте.
42 | 
43 | <a name="7"></a>
44 | 
45 | - [7](#7) Всегда помните: если вы можете решить проблемы каким-то способом, это не значит, что способ действительно стоит применять.
46 | 
47 |   И в верстке, и в программировании часто возникают ситуации, когда можно написать вполне рабочий код, но сделать это ненадежным способом, либо используя откровенные хаки, неочевидные другим разработчикам, либо просто оформив все некрасивым способом. Если перед вами появилась проблема, то нужно не только решить ее, но и сделать решение читабельным, масштабируемым и надежным. Во всех случаях, когда появляются сомнения, лучше спросить более опытных товарищей - это и вам позволит быстрее вырасти, и проекту получить более качественный код.
48 | 


--------------------------------------------------------------------------------
/JS/README.md:
--------------------------------------------------------------------------------
  1 | # JS
  2 | 
  3 | 1. [Хорошие практики](#1)
  4 | 2. [Именование переменных](#2)
  5 | 3. [Именование функций](#3)
  6 | 4. [Библиотеки](#4)
  7 | 5. [JQuery](#5)
  8 | 6. [Производительность](#6)
  9 | 7. [Архитектура](#7)
 10 | 8. [Безопасность](#8)
 11 | 
 12 | <a name="1"></a>
 13 | 
 14 | ## Хорошие практики
 15 | 
 16 | <a name="1.1"></a>
 17 | 
 18 | - [1.1](#1.1) Читаемость первостепенна
 19 | 
 20 |   Любое решение в первую очередь должно быть понятным и разбитым на логичные части, чтобы другие члены команды могли разобраться не только в назначении кода, но и в применяемых решениях без дополнительных оговорок.
 21 | 
 22 | <a name="1.2"></a>
 23 | 
 24 | - [1.2](#1.2) Все, что может быть написано на чистых html+css в рамках тех свойств, что дают заявленные браузеры - должно быть написано без применения JS.
 25 | 
 26 |   > _Это правило не должно противоречить предыдущему пункту_
 27 | 
 28 |   Это очень важное правило, так как:
 29 | 
 30 |   - Часто излишнее использование скриптов вводит других разработчиков в заблуждение, особенно, когда посреди работы скрипт внезапно меняет какие-либо свойства элемента.
 31 | 
 32 |   - Это уменьшает производительность веб-приложения.
 33 | 
 34 |   - Как правило код, написанный на html+css, гораздо проще изменять.
 35 | 
 36 |   Если реализация функционала на html+css возможна только с применением разных хаков, то тут уже стоит переходить на JS, чтобы поддерживаемость проекта не падала
 37 | 
 38 | <a name="1.3"></a>
 39 | 
 40 | - [1.3](#1.3) Избегать неявных критических зависимостей.
 41 | 
 42 |   Иногда на проекте могут возникнуть задачи, решая которые вы делаете систему уязвимой в плане падения, а не взлома. Пример из реальной жизни - подсчет суммы заказа на клиенте. Так как любым расчетам на клиенте нельзя доверять (ведь любой может простым HTTP запросом и другую цену послать), надо делать отдельный код на сервере, и при несовпадении значений заказ отклонять. Такого в идеале надо избегать по максимуму, но если это все-таки необходимо оставить в проекте, то надо сделать решение максимально безопасным (предусмотреть все случаи падений, зафиксировать их и обязательно уведомлять админов, если что-то пошло не так) и щедро осыпать комментариями и тестами.
 43 | 
 44 |   Вторым примером будет, когда вы в коде опираетесь на что-то из базы данных. Если в базе таких значений не будет, и ваша система упала - 99% что это ваша вина, даже если заполнение конкретно этого типа данных было священной обязанностью админов, которые прохалтурили.
 45 | 
 46 | <a name="1.4"></a>
 47 | 
 48 | - [1.4](#1.4) Знать и использовать стайлгайд от AirBnB.
 49 | 
 50 |   Сам он расположен [здесь](https://github.com/airbnb/javascript).
 51 | 
 52 |   Для него есть переводы, в том числе на русском, но читать надо оригинал, так как там описаны ES6 фичи. Все, что перечислено в гайде принять к исполнению, если это не перекрыто нашими правилами ниже.
 53 | 
 54 |   Для `eslint` есть конфиги [airbnb](https://www.npmjs.com/package/eslint-config-airbnb) и [airbnb-typescript](https://www.npmjs.com/package/eslint-config-airbnb-typescript). Обратите внимание, что обработка части правил от `airbnb` в этих конфигах может отсутствовать.
 55 | 
 56 | <a name="1.5"></a>
 57 | 
 58 | - [1.5](#1.5) Использовать `eslint` или аналоги.
 59 | 
 60 | <a name="1.6"></a>
 61 | 
 62 | - [1.6](#1.6) Методы.
 63 | 
 64 |   **Именование**:
 65 | 
 66 |   Имя метода должно быть `self descriptive`(описывать само себя). Из названия должно быть понятно для чего нужен метод и что он делает. Не должно быть причин задумываться о его внутренней реализации.
 67 | 
 68 |   **Параметры**:
 69 | 
 70 |   Если в метод необходимо передать много параметров, объединяйте их в один объект. Например, у вас есть метод, который рисует прямоугольник принимая координаты точек, ширину, высоту, цвет, толщину рамок и другие параметры. В таком случае, проще будет передать один объект ‘options’. Это снимет с нас обязанность держать в голове все параметры, а также их порядок, и позволит удобно сделать многие свойства с дефолтными значениями.
 71 | 
 72 |   В случае, когда параметры передаются объектом, получать их значения предпочтительнее с помощью деструктуризации.
 73 | 
 74 |   Если параметр опциональный, необходимо ему задать значение по умолчанию.
 75 | 
 76 |   **Тело**:
 77 | 
 78 |   Соблюдать принцип Single Responsibility. Метод должен выполнять только одну задачу (например, метод `createReport`, который создает отчет и отправляет его на сервер необходимо разделить на два: `createReport` и `sendReport`).
 79 | 
 80 |   Метод должен быть компактным. Обычно, длина метода варьируется в пределах 10-40 строк. Это не значит что ваш метод обязательно должен должен быть в таких рамках, но если ваш метод занимает 200 строк, это повод задуматься о том, можно ли его разделить на несколько отдельных методов. Про компактность методов можно почитать у С. Макконела “Совершенный код” и Р. Мартина “Чистый код”. Так же [здесь](https://softwareengineering.stackexchange.com/questions/133404/what-is-the-ideal-length-of-a-method-for-you) неплохое рассуждение о размерах метода.
 81 | 
 82 | <a name="1.7"></a>
 83 | 
 84 | - [1.7](#1.7) Делайте время жизни переменных как можно короче.
 85 | 
 86 |   Объявление переменной должно быть рядом с местом ее использования. Это дает более быстрое понимание того, что происходит в коде, плюс снижается вероятность неправильного использования переменной или ее перезапись.
 87 | 
 88 |   Более подробнее про время жизни переменной можно прочитать у С. Макконнелла в "Совершенном коде".
 89 | 
 90 | <a name="1.8"></a>
 91 | 
 92 | - [1.8](#1.8) Все кнопки сабмита должны быть внутри `<form>` вместе со всеми соответсвующими инпутами. Обработку завершения заполнения вешать на событие `submit` формы, а не клик по кнопке.
 93 | 
 94 |   Это очень важное правило для UX, которое часто упускается новичками. Еще раз: не вешайте обработку заполнения формы на событие `click` у кнопки, а вешайте на событие `submit` у формы. Как минимум, `submit` формы может быть вызван дополнительными путями - например, нажатие на enter у любого `input`, и, совершая ошибку, вы серьезно нарушаете UX всего сайта.
 95 | 
 96 | <a name="1.9"></a>
 97 | 
 98 | - [1.9](#1.9) Все проверки содержащие более одного условия должны быть вынесены.
 99 |   Выносить в отдельную архитектурную единицу - переменную или функцию.
100 | 
101 |   Плохо:
102 | 
103 |   ```javascript
104 |     if ((this.allowUpdate) && ((user.isAdmin) || (user.role === item.owner)) {
105 |       this.update(item.data);
106 |     }
107 |   ```
108 | 
109 |   Хорошо:
110 | 
111 |   ```javascript
112 |     function isUpdateAllowedForUser(user, item) {
113 |       return (this.allowUpdate) && ((user.isAdmin) || (user.role === item.owner);
114 |     }
115 |     //.. в нужном месте
116 |     if (this.isUpdateAllowedForUser(user, item)) {
117 |       this.update(item.data);
118 |     }
119 |   ```
120 | 
121 |   Тоже хорошо (пример ветвистого кода с кучей условий, где все именованно и раскидано, а поэтому понятно)
122 | 
123 |   ```javascript
124 |     const isTodayRequested = day === 'today';
125 |     const isTomorrowRequested = day === 'tomorrow';
126 |     const isDepartTomorrow = departure.day() !== now.day() && unix(departure)  unix(now);
127 |     const isDepartToday = departure.day() === now.day();
128 |     const isRequestedDayIncorrect = (isDepartToday && !isTodayRequested) || (isDepartTomorrow && !isTomorrowRequested);
129 |     const result = isRequestedDayIncorrect ? getPreviousDay(day) : day;
130 |   ```
131 | 
132 |   Вынос условий и их раскидывание по разным функциям/переменным позволяет каждому условию дать человеческое имя и потом ваши коллеги могут удобно читать все логические взаимосвязи не в шифре, а в удобном виде, почти как художественный текст.
133 | 
134 | <a name="1.10"></a>
135 | 
136 | - [1.10](#1.10) Всегда избегать неявного приведения типов в JS.
137 | 
138 |   В нашем любимом языке можно складывать массивы со строками, объекты с числами и тд. Но делать этого, конечно же, не надо. Всегда явно преобразуйте переменные к одному типу при их сложении, вычитании, делении и умножении.
139 | 
140 |   Плохо:
141 | 
142 |   ```javascript
143 |   const lifes = [true, false, false, true, true];
144 |   aliveTotal = 0;
145 |   for (let i = 0; i < lifes.length; i++) {
146 |     aliveTotal += lifes[i]; // тут мы к числу прибавляем элемент массива, который boolean.
147 |   }
148 |   ```
149 | 
150 |   Самое ужасное, что код этот будет работать, но в нем все слишком уязвимо и его чтобы поддерживать, надо постоянно в голове держать, что там булины с числами складываются.
151 | 
152 | <a name="1.11"></a>
153 | 
154 | - [1.11](#1.11) Не изменять прототипы стандартных конструкторов (например, `String.prototype` или `Function.prototype`), до тех пор пока вопрос внимательно не изучен и этот трюк не согласован со старшим разработчиком.
155 | 
156 | <a name="1.12"></a>
157 | 
158 | - [1.12](#1.12) Конструктор класса должен быть максимально легковесным.
159 | 
160 |   Например, если требуется провести поиск по DOM-дереву для задания значений полям класса, то нужно вынести этот функционал в отдельный метод. Так же в случае если нужно задать обработчики для событий - в отдельный метод.
161 | 
162 | <a name="1.13"></a>
163 | 
164 | - [1.13](#1.13) Выносить обработчики событий в отдельные функции.
165 | 
166 |   Не стоит создавать анонимные функции прямо в том же месте, где идет привязка к событию.
167 | 
168 |   Плохо:
169 | 
170 |   ```javascript
171 |   elem.addEventListener("click", function () {
172 |     alert("Спасибо!");
173 |   });
174 |   ```
175 | 
176 |   Хорошо:
177 | 
178 |   ```javascript
179 |   class Component {
180 |     bindEventListeners() {
181 |       topButton.addEventListener("click", this.handleStopButtonClick);
182 |     }
183 | 
184 |     handleStopButtonClick() {
185 |       // ...
186 |     }
187 |   }
188 |   ```
189 | 
190 | <a name="1.14"></a>
191 | 
192 | - [1.14](#1.14) В обработчиках работать не с контекстом (this), а с аргументом объекта ивента, который был передан свыше.
193 | 
194 |   Не полагаться на this при работе с объектами событий, а использовать первый параметр коллбека event.
195 |   Работать только с тем, что приходит из события. JS позволяет вносить дополнительные данные в event.
196 |   То есть не использовать "this.value". Вместо этого получать данные через объект события "e.currentTarget.value".
197 |   Плохо:
198 | 
199 |   ```javascript
200 |   handleButtonClick() {
201 |    const buttonWidth = $(this).width();
202 |    // ...
203 |   }
204 |   ```
205 | 
206 |   Хорошо:
207 | 
208 |   ```javascript
209 |   handleButtonClick(event) {
210 |    const buttonWidth = $(event.currentTarget).width();
211 |    // ...
212 |   }
213 |   ```
214 | 
215 | <a name="1.15"></a>
216 | 
217 | - [1.15](#1.15) Стараться по максимуму избегать циклов и использовать встроенные методы массивов.
218 | 
219 |   `.map`, `.filter` и тд обычно гораздо проще читаются, плюс функцию обработки одного элемента можно вынести и многократно использовать в разных местах.
220 | 
221 | <a name="1.16"></a>
222 | 
223 | - [1.16](#1.16) Не использовать литералы из бизнес-логики напрямую - надо создавать объект с константами.
224 | 
225 |   Если в бизнес-логике есть какой-то параметр, то надо создать где-то переменную, желательно в специальном месте для конфига, туда выносить все фиксированные значения, а в коде использовать их только по именам.
226 | 
227 |   Можно:
228 | 
229 |   ```javascript
230 |    if (status === ordersModule.ACTIVE_STATUS) {...}
231 |   ```
232 | 
233 |   Нельзя:
234 | 
235 |   ```javascript
236 |    if (status === 'active') {...}
237 |   ```
238 | 
239 | <a name="1.17"></a>
240 | 
241 | - [1.17](#1.17) Форматирование размещения импортов.
242 | 
243 |   Импорты объединяются в секции, секции разделяются переносом строки.
244 |   Для фронта выделяются три секции (в таком порядке размещения):
245 | 
246 |   - Абсолютные импорты из node_modules;
247 |   - Абсолютные импорты из src;
248 |   - Относительные импорты, отсортированные в порядке убывания переходов на более верхний уровень в дереве пути (через ../).
249 | 
250 |     Например:
251 | 
252 |   ```javascript
253 |   import * as React from "react";
254 |   import block from "bem-cn";
255 |   import { connect, Dispatch } from "react-redux";
256 |   import { bindActionCreators } from "redux";
257 |   import { arrayPush } from "redux-form";
258 | 
259 |   import { Modal } from "shared/view/elements";
260 |   import { IPreset } from "shared/types/models";
261 |   import { IAppReduxState } from "shared/types/app";
262 |   import { actions as notificationActions } from "services/notification";
263 |   import { selectors as configSelectors } from "services/config";
264 | 
265 |   import { actions, selectors } from "../../../redux";
266 |   import { managePresetsFormEntry } from "../../../redux/reduxFormEntries";
267 |   import { Presets } from "../../components/ManagePresets";
268 |   import "./ManagePresets.scss";
269 |   ```
270 | 
271 |   Также, для любого поддерева элемента пути не должно быть такого поддерева, импорты которого разделяются другим поддеревом такой же глубины.
272 |   Например:
273 |   Импорты поддерева `shared` (глубина 1) разделяются импортом поддерева services.
274 | 
275 |   ```javascript
276 |   import { IModel } from "shared/types/models";
277 |   import { i18nConnect } from "services/i18n";
278 |   import { Component } from "shared/view/components";
279 |   ```
280 | 
281 |   Правильно будет так:
282 | 
283 |   ```javascript
284 |   import { IModel } from "shared/types/models";
285 |   import { Component } from "shared/view/components";
286 |   import { i18nConnect } from "services/i18n";
287 |   ```
288 | 
289 |   Или в:
290 | 
291 |   ```javascript
292 |   import { IAppReduxState } from "shared/types/app";
293 |   import { Component } from "shared/view/components";
294 |   import { IModel } from "shared/types/models";
295 |   import { i18nConnect } from "services/i18n";
296 |   ```
297 | 
298 |   импорты поддерева `shared/types` (глубина 2) разделяются импортом поддерева `shared/view`. Правильно будет так:
299 | 
300 |   ```javascript
301 |   import { IAppReduxState } from "shared/types/app";
302 |   import { IModel } from "shared/types/models";
303 |   import { Component } from "shared/view/components";
304 |   import { i18nConnect } from "services/i18n";
305 |   ```
306 | 
307 | <a name="1.18"></a>
308 | 
309 | - [1.18](#1.18) Экспорты держать в конце файла.
310 | 
311 |   Плохо:
312 | 
313 |   ```javascript
314 |   export class Foo {
315 |     // ...
316 |   }
317 |   export class Bar {
318 |     // ...
319 |   }
320 |   // finita la comedia
321 |   ```
322 | 
323 |   Хорошо:
324 | 
325 |   ```javascript
326 |   class Foo {
327 |     // ...
328 |   }
329 |   class Bar {
330 |     // ...
331 |   }
332 |   export { Foo, Bar };
333 |   ```
334 | 
335 | <a name="1.19"></a>
336 | 
337 | - [1.19](#1.19) Если есть сомнения, поддерживает ли браузер какую-либо фичу - проверять непосредственно определена ли эта функция, а не сравнивать `user-agent` с названиями и версиями браузеров, которые по документации это поддерживают. А по хорошему вообще использовать [Modernizr](https://modernizr.com/).
338 | 
339 | <a name="1.20"></a>
340 | 
341 | - [1.20](#1.20) Избегать глобальных переменных.
342 | 
343 |   Почти в любом языке глобальные переменные - источник зла. В JavaScript это правило не исключение.
344 | 
345 |   Глобальные переменные делают работу программы непредсказуемой и усложняют изучение логики работы кода, плюс вызывает головокружение и гневные крики у опытных разработчиков при своем появлении.
346 | 
347 |   Чаще всего пользоваться глобальными переменными можно только потому что, так требуют олдскульные библиотеки, например Google Maps, которая создает глобальный объект google и карты можно кастомизировать только через него, и которая для колбека при своей инициации просит создать глобальную функцию, которую Google Maps потом сама вызовет.
348 | 
349 |   Можно на первых стадиях совсем простых проектов, где чуть-чуть анимаций на jquery использовать одну (и только одну) глобальную переменную, чтобы сохранять в нее модули и иметь возможность доступа к функциям из других js-файлов (по умолчанию сам js этого не поддерживает).
350 | 
351 | <a name="1.21"></a>
352 | 
353 | - [1.21](#1.21) К глобальным переменным обращаться только как к свойствам window.
354 | 
355 |   И создавать объекты только как свойства window, потому что объявление без var неочевидно - так же происходят переопределения переменных из замыкания и сложно отличить эти моменты.
356 | 
357 |   ```javascript
358 |   // тут правило нарушено, создается глобальная переменная без window, и обращение к ней тоже без window:
359 |   function test() {
360 |     foo = "hello world"; // обратить внимание, что переменная создана без var, значит она глобальная
361 |   }
362 |   test();
363 |   console.log(foo); // вывод 'hello world', обращение тоже без window
364 |   ```
365 | 
366 |   ```javascript
367 |   // тут следуют описанная глобальная переменная, как надо:
368 |   function test() {
369 |     window.foo = "hello world";
370 |   }
371 |   test();
372 |   console.log(window.foo); // вывод 'hello world', обращение как к >свойству объекта window
373 |   ```
374 | 
375 | <a name="1.22"></a>
376 | 
377 | - [1.22](#1.22) Используйте специальные обертки для логирования, а не сырой `console.log`.
378 | 
379 |   Вообще, логирование - это отдельное искусство, хорошие правила были описаны в [этой презентации](https://www.slideshare.net/nzakas/enterprise-javascript-error-handling-presentation/2-Whos_this_g_uy_P).
380 | 
381 |   У каждого лога должен быть префикс, который говорит из какого модуля вызван лог и в какое время он был вызван (таймстеймп);
382 | 
383 |   Разделять логирование как минимум на два уровня - `debug` и `production`, чтобы в production сборке не выводились логи для разработчиков;
384 | 
385 |   Все логи, которые ваша система производит, должны сохраняться в какую-либо единую переменную, чтобы в случае ошибок можно было сразу все отправить на сервер.
386 | 
387 |   <a name="1.23"></a>
388 | 
389 | - [1.23](#1.23) Старый код надо удалять, а не комментировать. Если он понадобится в дальнейшем, всегда можно будет посмотреть в истории коммитов.
390 | 
391 |   Это в первую очередь предназначено для ваших коллег - большие куски лишнего кода сбивают с толку, мешают поиску через `ctrl+F`, заставляют иногда отвлекаться на изучение кода. Так что лучше его скрыть в истории изменений.
392 | 
393 | <a name="1.24"></a>
394 | 
395 | - [1.24](#1.24) Все изменения в стилях, которые можно сделать через переключение классов у элемента, надо делать через добавление/удаление классов, а не простановку стилей у DOM-элементов. Так, например, можно переключать видимость элемента. Однако для непрерывно изменяющихся численных значений так сделать уже не получится, как например при изменении свойства `top` при скролле страницы, поэтому тут придётся все-таки проставлять напрямую у элемента значение в css-свойстве.\*\*;
396 | 
397 |   Это не только увеличит производительность (потому что за раз вы примените сразу все стили от нового класса), но и поможет потом переписать стили из css нормальным способом, потому что иначе стили будут инлайновые и из css их нельзя будет переопределить, кроме как через `!important`.
398 | 
399 | <a name="1.25"></a>
400 | 
401 | - [1.25](#1.25) Очень полезно понимать, как работают циклы перерисовки браузера и как можно проверить и увеличить производительность работы с DOM - здесь в статье перечислены [полезные источники](https://isobar-us.github.io/code-standards/#javascript_javascript_performance).
402 | 
403 | <a name="1.26"></a>
404 | 
405 | - [1.26](#1.26) Код должен быть без орфографических ошибок. Имена переменных, функций, комментарии должны быть написаны правильно.
406 | 
407 |   Обычно, чтобы избежать большинства ошибок, используют расширения для `IDE`, для `vscode` например есть хорошее расширение [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker).
408 | 
409 | <a name="1.27"></a>
410 | 
411 | - [1.27](#1.27) Вся работа со службами браузера (`navigator services`, `cookie`, `localStorage`) должна быть обернута в try/catch, т.к. это внешние по отношению к нашему коду службы, от которых не ясно, чего ждать. На спеки тут полагаться не стоит, т.к. есть и новые движки, которые имеют в том числе баги в своих сорцах.
412 | 
413 |   В сафари если включен режим инкогнито или если в браузере стоит блокировка `cookie`, то браузер будет райзить ошибку. Поэтому если ее не отловить, приложение посыпется :)
414 | 
415 | <a name="1.28"></a>
416 | 
417 | - [1.28](#1.28) Не расширять стандартные классы, такие как Array, Error, Map и другие, потому что вот [почему](https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work)
418 | 
419 | <a name="2"></a>
420 | 
421 | ## Именование переменных
422 | 
423 | <a name="2.1"></a>
424 | 
425 | - [2.1](#2.1) Именовать переменные по смыслу.
426 | 
427 |   Имя переменной должно полно и точно описывать сущность и ее предназначение.
428 | 
429 |   Имеется в виду не использовать в качестве имен date, result, array. Например, для текущей даты лучше использовать переменную today, а не date, для списка студентов лучше подойдет students а не array.
430 | 
431 | <a name="2.2"></a>
432 | 
433 | - [2.2](#2.2) Старайтесь не давать переменным слишком длинные имена.
434 | 
435 |   Как правило, чтобы раскрыть смысл переменной, достаточно около трех слов (10-15 символов). Переменные всегда используются в каком-то контексте, исходя из которого некоторые детали могут опускаться. Например, объект класса слайдера может содержать поле range, в котором содержится диапазон слайдера. Нет нужды называть это поле `sliderRange`, поскольку и так очевидно, что это относится к слайдеру. Длинные имена усложняют чтение кода и их следует использовать только тогда, когда более короткое имя неоднозначно и несет в себе слишком мало информации (учитывая контекст, о котором сказано выше) для понимания ее смысла.
436 | 
437 | <a name="2.3"></a>
438 | 
439 | - [2.3](#2.3) При именовании переменных использовать `camelCase`, так как это принято в JavaScript комьюнити.
440 | 
441 |   Если данные, которые приходят "со стороны" (например с бекенда), не в `camelCase` формате (`snake_case` или любой другой), имеет смысл нормализировать ключи для консистентности.
442 | 
443 | <a name="2.4"></a>
444 | 
445 | - [2.4](#2.4) Присваивайте булевым переменным имена, подразумевающие значение `true` или `false`.
446 | 
447 |   В основном мы юзаем префиксы в начале переменных: `is/are`, `has`, `with`. Порой название `boolean` переменной можно сформулировать как утверждение: `selectedColsWereChanged`, что позволит сделать код более читаемым и понятным.
448 | 
449 |   ```javascript
450 |   if (selectedColsWereChanged) { // do something... }
451 |   ```
452 | 
453 |   С другой стороны никто вас не ограничивает в использовании других конструкций английского языка: `will, should, etc`. которые позволят корректно выразить то, что вы хотите выразить в коде. Еще есть такой кейс: некоторые названия не нуждаются в дополнительной инфе, которая покажет что это `boolean` (либо по соображениям языка, либо так исторически сложилось): `pened, hidden, disabled, etc`. А вообще учите английский, чтобы грамотно выражать свои мысли и код :) Тогда вам не придется запоминать все эти штуки, и будет самим понятно почему так или иначе
454 | 
455 | <a name="2.5"></a>
456 | 
457 | - [2.5](#2.5) Использовать утвердительную форму булевых переменных.
458 | 
459 |   Имена, основанные на отрицании (такие как `notFound`, `notdone` и `notSuccessful`), при выполнении над переменной операции отрицания становятся куда менее понятны, например:
460 | 
461 |   ```javascript
462 |   if (not notFound) {..}
463 |   ```
464 | 
465 |   Подобные имена следует заменить на `found`, `done` и `processingComplete`, выполняя отрицание переменных в случае надобности. Так что для проверки нужного значения вы использовали бы выражение `found`, а не `not notFound`.
466 | 
467 | <a name="2.6"></a>
468 | 
469 | - [2.6](#2.6) Используйте объясняющие переменные.
470 | 
471 |   Плохо:
472 | 
473 |   ```javascript
474 |   const address = "One Infinite Loop, Cupertino 95014";
475 |   const cityZipCodeRegex = /^[^,\\]+[,\\\s]+(.+?)\s*(\d{5})?$/;
476 |   saveCityZipCode(
477 |     address.match(cityZipCodeRegex)[1],
478 |     address.match(cityZipCodeRegex)[2]
479 |   );
480 |   ```
481 | 
482 |   Хорошо:
483 | 
484 |   ```javascript
485 |   const address = "One Infinite Loop, Cupertino 95014";
486 |   const cityZipCodeRegex = /^[^,\\]+[,\\\s]+(.+?)\s*(\d{5})?$/;
487 |   const [_, city, zipCode] = address.match(cityZipCodeRegex) ?? [];
488 |   saveCityZipCode(city, zipCode);
489 |   ```
490 | 
491 | <a name="2.7"></a>
492 | 
493 | - [2.7](#2.7) Имя константы должно характеризовать абстрактную сущность, представляемую константой, а не конкретное значение.
494 | 
495 |   Например, нужна константа, отражающая количество рабочих дней:
496 | 
497 |   плохо: `FIVE`  
498 |   хорошо: `WORK_DAYS.`
499 | 
500 | <a name="3"></a>
501 | 
502 | ## Именование функций
503 | 
504 | <a name="3.1"></a>
505 | 
506 | - [3.1](#3.1) Все имена функций, за редкими исключениями (например, следование уже устоявшемуся соглашению в рамках какой-нибудь библиотеки), должны начинаться с глаголов.
507 | 
508 | <a name="3.2"></a>
509 | 
510 | - [3.2](#3.2) Функции высшего порядка, возвращающие функции, следует именовать по шаблону make + .\* + отглагольное существительное, где .\* — опциональный, синтаксически корректный набор слов уточняющий предназначение функции.
511 | 
512 |   Пример: `makeButtonClickHandler`.
513 | 
514 | <a name="3.3"></a>
515 | 
516 | - [3.3](#3.3) Обработчики событий.
517 | 
518 |   Под событиями понимаются не только DOM-события, но и какие-то абстрактные события, которые обрабатываются с помощью коллбэков, вроде `onClose` модального окна или `onLogin` формы логина):
519 | 
520 |   - Обработчики событий для БЭМ-элементов, а также для компонент, вложенных в БЭМ-элементы, именуются по шаблону `handleElementNameEventName`, где `ElementName` - имя БЭМ-элемента.
521 | 
522 |     Примеры:
523 | 
524 |     ```JSX
525 |     <button className="block__cancel-button" onClick={this.handleCancelButtonClick} />
526 |     <div className="block__first-name-input">
527 |       <Input onChange={this.handleFirstNameInputChange} />
528 |     </div>
529 |     ```
530 | 
531 |     Если компонента не вложена в БЭМ-элемент, то `ElementName` в данном случае стоит выбирать по смыслу, исходя из контекста\*\* (причем, поскольку БЭМ-элементы именуются по похожему принципу, то и БЭМ-элемент в данном случае назывался бы, скорее всего, так же):
532 | 
533 |     ```JSX
534 |     <div className="block">
535 |       <Button onClick={this.handleCancelButtonClick} />
536 |       <Input onChange={this.handleFirstNameInputChange} />
537 |     </div>
538 |     ```
539 | 
540 |     Обоснование: именуя колбэки по такому шаблону, мы не будем тратить время на придумывание имени и всегда можем понять предназначение колбэка лишь посмотрев на его имя.
541 | 
542 |     **Примечание**: в случаях, когда тело обработчика используется где-то ещё, то его следует выносить в отдельную функцию: например, обработчик `handleButtonClick`, выводящий список итемов, может передаваться только в пропс `onClick` БЭМ-элемента "button"; если же требуется вывести список итемов еще в каких-то других случаях, то следует сделать следующим образом:
543 | 
544 |     ```JSX
545 |     handleButtonClick() {
546 |       showItems();
547 |     }
548 | 
549 |     showItems() {
550 |       // ...
551 |     }
552 |     ```
553 | 
554 | <a name="4"></a>
555 | 
556 | ## Библиотеки
557 | 
558 | <a name="4.1"></a>
559 | 
560 | - [4.1](#4.1) Ни в коем случае никакой файл библиотеки не редактировать.
561 | 
562 |   Если есть небольшая полезная либа, у которой не хватает небольшой правки, то нужно сделать fork и отдельно в зависимостях указать путь до своей версии
563 | 
564 | <a name="4.2"></a>
565 | 
566 | - [4.2](#4.2) Изучайте best-practices для крупных библиотек, которые вы используете в проекте.
567 | 
568 |   Для Angular-а есть [руководство](https://github.com/mgechev/angularjs-style-guide/blob/master/README-ru-ru.md).  
569 |   Для React-а есть [руководство](https://github.com/airbnb/javascript/tree/master/react), [это](https://medium.com/lexical-labs-engineering/redux-best-practices-64d59775802e) и [наши best-practices](https://github.com/fullstack-development/front-end-best-practices/tree/master/React).
570 | 
571 | <a name="4.3"></a>
572 | 
573 | - [4.3](#4.3) Модули должны использоваться из node_modules.
574 | 
575 |   Если используются дополнительные модули, то в package.json должны быть прописаны пути до локальных модулей, которые вы установили.
576 | 
577 | <a name="4.4"></a>
578 | 
579 | - [4.4](#4.4) Выбор библиотеки.
580 | 
581 |   Когда для поставленной задачи можно использовать библиотеку, никогда не делать выбор за первой попавшейся в поисковике. Надо сначала проанализировать как минимум 3 самых популярных решения и для каждого:
582 | 
583 |   - Eсть ли у нее отдельный публичный репозиторий и где он находится.
584 |   - Eсть ли у нее документация и описывает ли она использование библиотеки для нашей поставленной проблемы;
585 |   - если доков нет или нет нормального описания, надо внимательно изучить код библиотеки и понять API, которое позволит решить проблему;
586 |   - осмотреть открытые `issue` (хотя бы пробежать глазами по первым двум страницам) и изучить те, что могут повлиять на работу библиотеки в контексте нашего проекта;
587 |   - принять решение о использовании библиотеки только совместно с другими равными по статусу или старшими фронтенд-разработчиками из команды;
588 |   - Обратить внимание, сопровождается ли библиотека, или является заброшенной. Есть ли pull request'ы, и есть ли в них обсуждения. Принимаются ли pull request'ы;
589 |   - Обратить внимание, протестирована ли библиотека. Если библиотека протестирована, то стоит уделить внимание тестам, которые были написаны для неё: какие use-cases покрываются в тестах, и решают ли эти use-cases проблемы, ради которых вы хотите её использовать. Так же стоит уделить внимание к качеству самих тестов, не являются ли они хрупкими к изменениям и т.д. Если к рассматриваемой библиотеке тестов нет, возможно, вам стоит поискать другую библиотеку.
590 | 
591 | <a name="5"></a>
592 | 
593 | ## JQuery
594 | 
595 | > _или все библиотеки со схожим API, где мы ищем элементы по селекторам и манипулируем ими как с js-переменными, например:_
596 | >
597 | > ```javascript
598 | > const $newMessage = $('<li class="js-message" />');
599 | > const $messageList = $body.find("ul.js-messages");
600 | > $messageList.append($newMessage);
601 | > ```
602 | 
603 | <a name="5.1"></a>
604 | 
605 | - [5.1](#5.1) Все классы, которые используем для поиска по DOM-у должны начинаться с префикса `js-`.
606 | 
607 |   Например, есть кнопка, по клику открывающая попап - нам надо продублировать ее класс и добавить туда этот префикс:
608 | 
609 |   ```html
610 |   <div class="open-popup-button js-open-popup-button"></div>
611 |   ```
612 | 
613 |   В итоге в js-файлах мы используем только второй класс:
614 | 
615 |   ```javascript
616 |   $('.js-open-popup-button').click(...);
617 |   ```
618 | 
619 |   Это поможет избежать неожиданной поломки скриптов при смене верстки и наоборот.
620 | 
621 | <a name="5.2"></a>
622 | 
623 | - [5.2](#5.2) Конкатенировать селекторы, если с элементами будет проводиться одна и та же работа.
624 | 
625 |   ```javascript
626 |   $("form p").addClass("valid");
627 |   $("form li").addClass("valid");
628 |   $("form span").addClass("valid");
629 |   // - это лучше заменить на это:
630 |   $("form p, form li, form span").addClass("valid");
631 |   ```
632 | 
633 | <a name="5.3"></a>
634 | 
635 | - [5.3](#5.3) Все переменные, которые поддерживают jQuery API, должны начинаться со знака.
636 | 
637 |   Например:
638 | 
639 |   ```javascript
640 |   const $body = $("body");
641 |   const $lists = $body.find("ul");
642 |   ```
643 | 
644 |   А тут уже не jQuery API и переменные не должны начинаться с \$
645 | 
646 |   ```javascript
647 |   // это нативной метод, который тоже возвращает нативной DOM-элемент
648 |   const chatBox = document.getElementById("chat-box");
649 | 
650 |   // изъятие по индексу возвращает уже нативной DOM-элемент
651 |   const firstList = $lists[0];
652 |   ```
653 | 
654 | <a name="5.4"></a>
655 | 
656 | - [5.4](#5.4) Обработчики событий всегда именовать.
657 | 
658 |   ```javascript
659 |   // Надо не просто делать
660 |   $(window).scroll(...);
661 |   // а
662 |   $(window).on('scroll.myComponent', function (event) {...});
663 |   ```
664 | 
665 |   Это позволит легко отсоединять обработчики, когда нужда в них отпадет.
666 | 
667 | <a name="5.5"></a>
668 | 
669 | - [5.5](#5.5) Поддерживать модульность.
670 |   Так как идеология jquery не несет никаких знаний по тому, как организовывать более-менее сложные приложения (когда больше 3-х элементов на странице), то приходится все придумывать самим. Главные принципы, которым лучше следовать, чтобы код был чистый, а архитектура предсказуемой и понятной для других участников команды:
671 | 
672 |   <a name="5.5.1"></a>
673 | 
674 |   1. [5.5.1](#5.5.1) делить приложение на смысловые блоки. Все, что смотрится, как отдельный независимый элемент должно быть вынесено в отдельный блок. Весь js-код по нему должен быть в отдельном файле и строго отделен от остального приложения. У этого кода должен быть четкий и понятный интерфейс, который бы позволял внешнему миру общаться с блоком.
675 | 
676 |   <a name="5.5.2"></a>
677 | 
678 |   1. [5.5.2](#5.5.2) гарантировать независимость двух одинаковых блоков на одной странице друг от друга. То есть, если на странице два слайдера, то заранее на архитектурном уровне побеспокоиться, чтобы никакие события первого слайдера не влияли на второй.
679 | 
680 |   <a name="5.5.3"></a>
681 | 
682 |   1. [5.5.3](#5.5.3) Предыдущего условия (независимости однородных блоков) можно достичь, если js-код каждого блока обрамлять в класс, а затем для каждого встречного html-блока в верстке создавать по инстансу класса. В инстанс класса тогда можно сохранять сам DOM-элемент и потом только через него искать все вложенные элементы и только на них вешать обработчики.
683 | 
684 |   <a name="5.5.4"></a>
685 | 
686 |   1. [5.5.4](#5.5.4) Выше было требование, что все обработчики должны быть отименованы. Тут это принимает еще более строгий характер — имена обработчиков для разных инстансов одного и того же класса должны быть уникальными, чтобы \$(block).off(...) отключал события только для текущего инстанса блока, не для всех инстансов, а то неожиданно для разработчика сразу будут отключены обработчики события для всех слайдеров на странице.
687 | 
688 |   <a name="5.5.5"></a>
689 | 
690 |   1. [5.5.5](#5.5.5) Также классы позволяют сделать структуру всех блоков одинаковой и предсказуемой — зная, как устроен блок slider, уже можно предсказать, как устроены блоки calendar и dropdown. У всех у них будут методы инициализации и поиска вложенных DOM-элементов, у всех будет код, который навешивает события, у всех будет интерфейс по удалению инстанса и тд. Так что лучше сразу позаботиться об одинаковой структуре и все максимально стандартизировать.
691 | 
692 | ## Производительность
693 | 
694 | <a name="6.1"></a>
695 | 
696 | - [6.1](#6.1) В проектах на jquery или чем-либо, где поиск DOM-элементов идет по селекторам - надо кэшировать все найденные элементы.
697 | 
698 |   ```javascript
699 |   $foodItem = $("#shopping-list li");
700 | 
701 |   $foodItem.click(function () {
702 |     // do something...
703 |   });
704 |   ```
705 | 
706 | <a name="6.2"></a>
707 | 
708 | - [6.2](#6.2) Все операции с DOM-ом лучше сначала проводить на виртуальных элементах, а потом сразу целиком вставлять в документ страницы.
709 | 
710 |   здесь в цикле в DOM внедряется каждый элемент массива один за одни, в итоге имеем кучу циклов перерисовки:
711 | 
712 |   ```javascript
713 |   for (let i=0; i < items.length; i++) {
714 |       const item = document.createElement("li");
715 |       item.appendChild(document.createTextNode("Option " + i);
716 |       list.appendChild(item);
717 |   }
718 |   ```
719 | 
720 |   здесь мы в цикле вносим элемент в виртуальный элемент, а затем уже целиком за раз это внедряем в реальный DOM и получаем один цикл перерисовки:
721 | 
722 |   ```javascript
723 |   const fragment = document.createDocumentFragment();
724 |   for (let i=0; i < items.length; i++) {
725 |       const item = document.createElement('li');
726 |       item.appendChild(document.createTextNode('Option ' + i);
727 |       fragment.appendChild(item);
728 |   }
729 |   list.appendChild(fragment);
730 |   ```
731 | 
732 | <a name="6.3"></a>
733 | 
734 | - [6.3](#6.3) Избегать сложных селекторов.
735 | 
736 |   В зависимости от типа и сложности css-селектора зависит производительность рендеринга и анимации сайта. Например использование в `transition` селектора по атрибуту (например `input[type="text"] { transform: translateX(50%)` } теоретически может замедлить саму анимацию. Те же правила экстраполируются на всю страницу. Чем сложнее css-селекторы (много вложенности и нетривиальных селекторов с необходимостью часто и много считать приоритеты), тем сложнее браузеру рендерить страницу, т.к. приходится применять стили согласованно между друг другом и анализировать DOM-дерево, что, конечно, не самая простая задача с точки зрения производительности сама по себе.
737 | 
738 | <a name="6.4"></a>
739 | 
740 | - [6.4](#6.4) Все js-ки подключаем внизу страницы перед закрывающимся тегом `<body>`.
741 | 
742 | <a name="6.5"></a>
743 | 
744 | - [6.5](#6.5) Полезные материалы:
745 | 
746 |   - [Perf.Rocks](https://perf.rocks/)
747 |   - [calendar](https://calendar.perfplanet.com/2014/)
748 |   - [PageSpeed Insights Rules](https://developers.google.com/speed/docs/insights/rules)
749 |   - [avascriptrocks](http://javascriptrocks.com/)
750 | 
751 | <a name="8"></a>
752 | 
753 | ## Архитектура
754 | 
755 | <a name="7.1"></a>
756 | 
757 | - [7.1](#7.1) Модульность - наше все!
758 | 
759 |   Обязательно дробить приложение на разные модули, даже если сайт - просто статичный контент с несколькими обработчиками событий, которые вешаются через jquery.
760 | 
761 |   Для импорта модулей друг в друга использовать webpack, если проект совсем простой, можно обойтись созданием одного (!) глобального объекта и у него свойствами сохранять разные модули.
762 | 
763 |   Для каждого модуля - только один файл. Без использования webpack и других сборщиков сами заботьтесь о том, чтобы не загрязнять глобальную область видимости (оборачивать все содержимое каждого файла в самовызывающуюся функцию).
764 | 
765 |   В рамках одного модуля описывать только схожий функционал, который объединен смыслом. Это называется [связность](<https://ru.wikipedia.org/wiki/%D0%A1%D0%B2%D1%8F%D0%B7%D0%BD%D0%BE%D1%81%D1%82%D1%8C_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)>). Обратная сторона медали - [зацепление](<https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D1%86%D0%B5%D0%BF%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)>), когда модули друг от друга сильно зависят - этого как раз надо избегать. То есть общий принцип - модули надо разбить так, чтобы внутри каждого модуля была максимальная схожесть области работы, а между модулями было максимальное различие. Например, в статистике сегмантация выполняется по таким же принципам, все группы должны состоять из максимально похожих элементов и при этом максимально отличаться друг от друга :).
766 | 
767 | <a name="7.2"></a>
768 | 
769 | - [7.2](#7.2) В рамках модуля четко делить на слои и не мешать логику работы с DOM и работу с данными (например, ajax-запросы).
770 | 
771 |   Вообще всю работу с самими данными максимально отделять от работы с DOM и обработке событий пользователя (клики, сабмиты и тд).
772 | 
773 |   Желательно для каждого приложения более менее формализовать структуру модуля, описать ее в конкретном виде для всех проектов невозможно, так как что-то пишется на `React`, что-то на `React+Redux`, а что-то на простом `jquery`. Для последнего этот пункт наиболее важен, но при этом наиболее неопределен.
774 | 
775 | <a name="7.3"></a>
776 | 
777 | - [7.3](#7.3) Избегать мутаций одной переменной сразу в нескольких функциях.
778 | 
779 |   Пример плохого кода:
780 | 
781 |   ```javascript
782 |   const box = {};
783 | 
784 |   function addBall(box) {
785 |     box.ball = { radius: 2 };
786 |   }
787 | 
788 |   function addFood(box) {
789 |     box.food = { carrot: 4 };
790 |   }
791 | 
792 |   function addShoes(box) {
793 |     box.shoes = { sneakers: 2 };
794 |   }
795 | 
796 |   addBall(box);
797 |   addFood(box);
798 |   addShoes(box);
799 |   ```
800 | 
801 |   Из-за таких действий область использования переменной становится слишком большой и тяжело понять, какая именно функция и когда изменила переменную. Когда произойдет ошибка в 10-ой функции, будет непонятно почему box содержит 5 пар кроссовок и 15 морковок.
802 | 
803 |   Используйте чистые функции, пересоздавайте объекты, а не мутируйте их, а еще лучше формализуйте все возможности изменить ваш объект, как это делает `Redux` для переменной состояния приложения.
804 | 
805 | <a name="7.4"></a>
806 | 
807 | - [7.4](#7.4) В js нет публичных и частных свойств, поэтому частные методы просто делать с префиксами `"_"` (нижнее подчеркивание).
808 | 
809 |   ```javascript
810 |   class Person {
811 |     constructor(name) {
812 |       this.name = name;
813 |     }
814 | 
815 |     public() {
816 |       console.log("Call me from the outer modules");
817 |     }
818 | 
819 |     _private() {
820 |       console.log(
821 |         "Call me only from the class Person methods, for example from public"
822 |       );
823 |     }
824 |   }
825 |   ```
826 | 
827 | <a name="7.5"></a>
828 | 
829 | - [7.5](#7.5) При написании класса все публичные методы объявляйте первыми, причем самым первым должен идти конструктор, все приватные методы группируйте по смыслу внизу класса
830 | 
831 | <a name="8"></a>
832 | 
833 | ## Безопасность
834 | 
835 | - [Browser Security Handbook from Google](https://code.google.com/archive/p/browsersec/wikis/Main.wiki).
836 | - [HTML5 Security Cheatsheet](https://html5sec.org/#javascript).
837 | - [Web Security Basics](https://github.com/vasanthk/web-security-basics).
838 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Front-end best practices
 2 | 
 3 | Стандарты компании для frontend-проектов.
 4 | 
 5 | ## Разделы стандартов
 6 | 
 7 | 1. [Инициализация](./Initiation.md)
 8 | 2. [HTML](./HTML/README.md)
 9 | 3. [CSS](./CSS/README.md)
10 | 4. [JS](./JS/README.md)
11 | 5. [React](./React/README.md)
12 | 6. [Окружение](./Environment/README.md)
13 | 
14 | ## Contributing
15 | 
16 | Если вы хотите внести свой вклад в развитие наших стандартов, пожалуйста следуйте практике issue first. Перед тем, как создать pull request, заведите issue, подробно опишите, в чем проблема, и как ваша идея позволяет решить ее. Пропускать этап создания issue и сразу создавать pull request можно только в случаях, когда проблема и решение очевидны (например, опечатка или орфографическая ошибка).
17 | 


--------------------------------------------------------------------------------
/React/Optimization.md:
--------------------------------------------------------------------------------
  1 | # Оптимизация React
  2 | 
  3 | Данный топик частично основан на [докладе](https://youtu.be/DDN9himU5PE?si=6syNK_SBnJbYaHO8) Тёмы Синюкова c HolyJS. 
  4 | 
  5 | 1. [Введение](#1)
  6 | 2. [throttle/debounce](#2)
  7 | 3. [Вынос состояния](#3)
  8 | 4. [Children Prop](#4)
  9 | 5. [useContext](#5)
 10 | 6. [Правильный условный рендеринг](#6)
 11 | 7. [Использование key](#7)
 12 | 
 13 | <a name="1"></a>
 14 | 
 15 | ## Введение
 16 | 
 17 | Для начала надо понять, что не каждый рендер в React вызывает отрисовку DOM в браузере. Например, компонент ниже будет рендериться каждую секунду и каждую секунду будет выполняться отрисовка браузером:
 18 | 
 19 | ```tsx
 20 | export const WithChangeView = () => {
 21 |   const [count, setCount] = useState(0);
 22 | 
 23 |   useEffect(() => {
 24 |     const interval = setInterval(() => setCount((count) => count + 1), 1000);
 25 |     return () => clearInterval(interval);
 26 |   }, []);
 27 | 
 28 |   return <div>{count}</div>;
 29 | };
 30 | ```
 31 | 
 32 | А в примере ниже, компонент так же будет рендериться каждую секунду, но отрисовка в браузере произойдёт лишь один раз:
 33 | 
 34 | ```tsx
 35 | const WithoutChangeView = () => {
 36 |   const [count, setCount] = useState(0);
 37 | 
 38 |   useEffect(() => {
 39 |     const interval = setInterval(() => setCount((count) => count + 1), 1000);
 40 |     return () => clearInterval(interval);
 41 |   }, []);
 42 | 
 43 |   return <div>Hello</div>;
 44 | };
 45 | ```
 46 | 
 47 | Если вы столкнулись с проблемами производительности, то в первую очередь необходимо бороться с лишними рендерами, когда эти рендеры приводят к отрисовке браузером (как в первом примере). А уже потом со всеми остальными. 
 48 | 
 49 | <a name="2"></a>
 50 | 
 51 | ## throttle/debounce для часто срабатываемых событий
 52 | 
 53 | В случае, если вы подписываетесь на событие, которое может срабатывать слишком часто (время, скролл, ресайз, движение мыши и т.д.), например несколько раз в секунду и вам это явно не нужно, воспользуйтесь throttle или debounce. В чём разница можно почитать [тут](http://xandeadx.ru/blog/javascript/956?ysclid=lz14uc5emd795136121). 
 54 | 
 55 | Один из примеров, это подписка на событие `scroll`, которое будет срабатывать крайне часто. И вряд ли вам вам нужно реагировать на это событие так же часто. Решение - обернуть обработчик в функцию `throttle`:
 56 | 
 57 | ```tsx
 58 | export const ScrollWithThrottle = () => {
 59 |   const [scroll, setScroll] = useState(0);
 60 | 
 61 |   useEffect(() => {
 62 |     const handleWindowScroll = () => {
 63 |       setScroll(window.scrollY);
 64 |     };
 65 |     const throttledHandleWindowScroll = throttle(100, handleWindowScroll);
 66 | 
 67 |     window.addEventListener('scroll', throttledHandleWindowScroll);
 68 |     return () => window.removeEventListener('scroll', throttledHandleWindowScroll);
 69 |   }, []);
 70 | 
 71 |   return <div>{scroll}</div>;
 72 | };
 73 | ```
 74 | <a name="3"></a>
 75 | 
 76 | ## Вынос состояния
 77 | 
 78 | Допустим у вас есть компонент с собственным состоянием, который при этом подключает какой-то тяжёлый `<SlowComponent />`. При каждом изменении состояния, `<SlowComponent />` будет перерендериваться:
 79 | 
 80 | 
 81 | ```tsx
 82 | const Component = () => {
 83 |   const [count, setCount] = useState(0);
 84 | 
 85 |   return (
 86 |     <div>
 87 |       <span>{count}</span>
 88 |       <button onClick={() => setCount((count) => count + 1)}>Plus</button>
 89 |       <SlowComponent />
 90 |     </div>
 91 |   );
 92 | };
 93 | ```
 94 | 
 95 | Решение - вынести состояние в отдельный компонент:
 96 | 
 97 | ```tsx
 98 | const Component = () => {
 99 |   return (
100 |     <div>
101 |       <TriggerComponent />
102 |       <SlowComponent />
103 |     </div>
104 |   );
105 | };
106 | 
107 | const TriggerComponent = () => {
108 |   const [count, setCount] = useState(0);
109 | 
110 |   return (
111 |     <>
112 |       <span>{count}</span>
113 |       <button onClick={() => setCount((count) => count + 1)}>Plus</button>
114 |     </>
115 |   );
116 | };
117 | ```
118 | 
119 | Теперь изменение состояние не приводит к перерендеру `<SlowComponent />`.
120 | 
121 | <a name="4"></a>
122 | 
123 | ## Использование Children Prop
124 | 
125 | У вас есть компонент, подключащий множество других компонентов и содержащий логику, которая заставляет этот компонент часто перерендериваться. Как итог, все его потомки будут тоже часто перерендериваться:
126 | 
127 | ```tsx
128 | const Page = () => {
129 |   const [isHovered, setIsHovered] = useState(false);
130 |   const [scroll, setScroll] = useState();
131 | 
132 |   // Logic
133 | 
134 |   return (
135 |     <div
136 |       onScroll={setScroll}
137 |       onMouseEnter={() => setIsHovered(true)}
138 |       onMouseLeave={() => setIsHovered(false)}
139 |     >
140 |       <Header />
141 |       <Content />
142 |       <Footer />
143 |     </div>
144 |   );
145 | };
146 | ```
147 | 
148 | Решение - вынести рендер компонентов на уровень выше, передавая результат рендера через пропсы. 
149 | 
150 | ```tsx
151 | const Layout = ({ top, center, bottom }) => {
152 |   const [isHovered, setIsHovered] = useState(false);
153 |   const [scroll, setScroll] = useState();
154 | 
155 |   // Logic
156 |   
157 |   return (
158 |     <div
159 |       onScroll={setScroll}
160 |       onMouseEnter={() => setIsHovered(true)}
161 |       onMouseLeave={() => setIsHovered(false)}
162 |     >
163 |       <div>{top}</div>
164 |       <div>{center}</div>
165 |       <div>{bottom}</div>
166 |     </div>
167 |   );
168 | };
169 | 
170 | const Page = () => {
171 |   return (
172 |     <Layout
173 |       top={<Header />}
174 |       center={<Content />}
175 |       bottom={<Footer />}
176 |     />
177 |   );
178 | };
179 | ```
180 | 
181 | Теперь компоненты `Header`, `Content` и `Footer` не являются прямыми потомками в `Layout`, и не будут перерендериваться при изменении состояний в `Layout`.
182 | 
183 | <a name="5"></a>
184 | 
185 | ## useContext
186 | 
187 | При работе с `useContext` есть сразу несколько подводных камней.
188 | 
189 | 1. В примере ниже, все элементы внутри `Provider` являются его прямыми потомками. Это приведёт к тому, что любое изменение состояние `theme` приведёт к перерендеру всех дочерних элементов. Даже тех, кто не использует значение из контекста.
190 |     ```tsx
191 |     const Context = React.createContext();
192 | 
193 |     const Component = () => {
194 |       const [theme, setTheme] = useState("default");
195 | 
196 |       return (
197 |         <Context.Provider value={{ theme, setTheme }}>
198 |           <div>
199 |             <Child />
200 |             И еще очень много дочерних
201 |           </div>
202 |         </Context.Provider>
203 |       );
204 |     };
205 |     ```
206 |     Что бы этого избежать, всегда выносите `Provider` в отдельный компонент и передавайте потомков через проп `children`. 
207 |     ```tsx
208 |     const Context = React.createContext();
209 |     
210 |     const Component = () => {
211 |       return (
212 |         <ThemeProvider>
213 |           <div>
214 |             <Child />
215 |             И еще очень много дочерних
216 |           </div>
217 |         </ThemeProvider>
218 |       );
219 |     };
220 | 
221 |     const ThemeProvider = ({ children }) => {
222 |       const [theme, setTheme] = useState("default");
223 | 
224 |       return (
225 |         <Context.Provider value={{ theme, setTheme }}>
226 |           {children}
227 |         </Context.Provider>
228 |       );
229 |     };
230 |     ```
231 | 2. В предыдущем примере есть другая важная проблема - это хранение объекта в `value`. При каждом изменении состояния и перерендере `ThemeProvider`, объект будет создаваться заново и все компоненты, которые читают контекст, будут перерендериваться. Что бы этого избежать, можно обернуть значение в `useMemo`.
232 |     ```tsx
233 |     const Context = React.createContext();
234 |     
235 |     const ThemeProvider = ({ children }) => {
236 |       const [theme, setTheme] = useState("default");
237 |       const value = useMemo(() => ({ theme, setTheme }), [theme, setTheme]);
238 |       
239 |       return (
240 |         <Context.Provider value={value}>
241 |           {children}
242 |         </Context.Provider>
243 |       );
244 |     };
245 |     ```
246 | 3. Но это не решит всех проблем, ведь все компоненты, которые используют только `setTheme` будут перерендериваться при изменении `theme`, хотя сами они `theme` никак не используют. Это решается разнесением контекста. Один контекст для состояния, другой для сеттера.
247 |     ```tsx
248 |     const Context = React.createContext();
249 | 
250 |     const SetterContext = React.createContext();
251 | 
252 |     const ThemeProvider = ({ children }) => {
253 |       const [theme, setTheme] = useState("default");
254 | 
255 |       return (
256 |         <Context.Provider value={theme}>
257 |           <SetterContext.Provider value={setTheme}>
258 |             {children}
259 |           </SetterContext.Provider>
260 |         </Context.Provider>
261 |       );
262 |     };
263 |     ```
264 |     Вот теперь всё хорошо, компоненты использующие `setTheme` не будут перерендериваться при изменении `theme`.
265 | 
266 |     А вообще, лучше используйте стейт менеджеры, которые решают проблемы оптимального ререндера компонентов (MobX, Zustand и др.). 
267 | 
268 | <a name="6"></a>
269 | 
270 | ## Правильный условный рендеринг
271 | 
272 | Допустим, у вас есть компонент, который должен отображаться только авторизованным пользователям.
273 | 
274 | ```tsx
275 | const AuthorizedUser = () => {
276 |   // здесь много хуков и логики
277 | 
278 |   const isAuthorized = useIsAuthorized();
279 | 
280 |   if (!isAuthorized) {
281 |     return null;
282 |   }
283 |   return <>...</>;
284 | };
285 | ```
286 | 
287 | Проблема в том, что все хуки и логика, находящиеся перед `if` всегда выполнятся. Решение - проверку на рендер компонента `AuthorizedUser` делать в родителе. Для переиспользования вы можете вынести проверку в HOC:
288 | 
289 | ```tsx
290 | const withAuthorize = ({ AuthorizedUser, UnAuthorizedUser }) => {
291 |   const Component = function WithAuthorizeComponent({ authProps, unAuthProps }) {
292 |     const isAuthorized = useIsAuthorized();
293 |     return isAuthorized ? (
294 |       <AuthorizedUser {...authProps} />
295 |     ) : (
296 |       <UnAuthorizedUser {...unAuthProps} />
297 |       );
298 |   };
299 | 
300 |   return Component;
301 | };
302 | ```
303 | 
304 | <a name="7"></a>
305 | 
306 | ## Использование key
307 | 
308 | Вы можете указать React, что ваш элемент не изменился и его не нужно пересоздавать. В примере ниже, компонент `Child` может находится в разных позициях и React по умолчанию назначит ему разный `key`:
309 | 
310 | ```tsx
311 | const Example = ({ isSecondChildVisible }) => {
312 |   if (!isSecondChildVisible) {
313 |     return <Child />; // здесь key = 1
314 |   }
315 | 
316 |   return (
317 |     <>
318 |       <div>Visible</div> // Здесь key = 1
319 |       <Child /> // Здесь key = 2
320 |     </>
321 |   );
322 | };
323 | ```
324 | 
325 | При изменении условия, у `Child` будет разный `key` и React начнёт размонтировать первый `Child` и  монтировать второй `Child`. Что бы этого избежать, можно явно задать одинаковый `key` для обоих `Child`:
326 | 
327 | ```tsx
328 | const Example = ({ isSecondChildVisible }) => {
329 |   if (!isSecondChildVisible) {
330 |     return <Child key="child" />; 
331 | 
332 |   return (
333 |     <>
334 |       <div>Visible</div> 
335 |       <Child key="child" /> 
336 |     </>
337 |   );
338 | };
339 | ```
340 | 
341 | Теперь при изменении условия, React увидит, что у элементов `Child` одинаковый `key` и их нужно просто поменять местами, без необходимости размонтирования/монтирования. 
342 | 
343 | Почему это так работает? Читайте [тут](https://gist.github.com/zagazat/db926ec7ab69061934246a55b64913c3) и смотрите этот [таймкод](https://youtu.be/DDN9himU5PE?si=TLGEiuY5ZP8v1VEk&t=2183).


--------------------------------------------------------------------------------
/React/README.md:
--------------------------------------------------------------------------------
  1 | # React
  2 | 
  3 | 1. [Компоненты](#1)
  4 | 2. [Пропсы](#2)
  5 | 3. [Иконки](#3)
  6 | 4. [SVG](#4)
  7 | 5. [Экспорт](#5)
  8 | 6. [Переменные окружения](#6)
  9 | 7. [Работа с API](#7)
 10 | 8. [Общие принципы работы со стейт менеджерами](#8)
 11 | 9. [Оптимизация](#9)
 12 | 10. [Общее](#10)
 13 | 
 14 | ## Интро
 15 | 
 16 | В этом топике собраны best practices, как напрямую касающиеся React, так и те, которые так или иначе затрагивают будни frontend-разработчика. Помимо самих best practices, в этом топике также содержатся правила, относящиеся больше к стайлгайду, нежели к лучшим практикам. Таким образом хотелось бы прийти к большему однообразию в написании кода на разных проектах, что упростит переход разработчика с одного проекта на другой, поскольку при чтении и анализе кода/структуры проекта будет прилагаться меньше когнитивных усилий. Также это может уменьшить количество холиваров по поводу разных стилей написания кода (но это неточно :). Следует не забывать, что не стоит впадать в крайности. Иногда какое-то правило может только мешать и делать хуже, так как всех кейсов не опишешь.
 17 | 
 18 | Так же не забываем про топик [JS](../JS/README.md), в котором много полезных правил вне зависимости от фреймворков.
 19 | 
 20 | <a name="1"></a>
 21 | 
 22 | ## Компоненты
 23 | 
 24 | <a name="1.1"></a>
 25 | 
 26 | - [1.1](#1.1) Именование переменной и функции при вызове `useState` должно быть одинаковым, только к функции прибавляется слово `set`.
 27 | 
 28 |   Плохо:
 29 |   ```typescript
 30 |   const [isModalOpen, openModal] = useState();
 31 |   ```
 32 |   Хорошо:
 33 |   ```typescript
 34 |   const [isModalOpen, setIsModalOpen] = useState();
 35 |   ```
 36 | 
 37 | <a name="1.2"></a>
 38 | 
 39 | - [1.2](#1.2) Разделяйте хуки `useEffect` для разных задач - [React docs](https://ru.reactjs.org/docs/hooks-effect.html#tip-use-multiple-effects-to-separate-concerns) 
 40 | 
 41 | <a name="1.3"></a>
 42 | 
 43 | - [1.3](#1.3) Помещайте вызовы `useEffect` в самый низ, перед `return` (есть исключение, описанное в конце [1.4](#1.4)).
 44 | 
 45 | <a name="1.4"></a>
 46 | 
 47 | - [1.4](#1.4) Не создавайте лишние JSX переменные. В подавляющем большинстве случаев их содержимое можно вставить внутрь оператора `return`.
 48 | 
 49 |   Плохо:
 50 |   ```typescript
 51 |   const MyComponent: FC<Props> = ({ array, condition }) => {
 52 |     const list = array.map((item) => <li key={item}>{item}</li>);
 53 | 
 54 |     const conditionalRender = condition ? <div /> : <section />;
 55 | 
 56 |     return (
 57 |       <div>
 58 |         <ul>{list}</ul>
 59 |         {conditionalRender}
 60 |       </div>
 61 |     );
 62 |   };
 63 |   ```
 64 |   Хорошо:
 65 |   ```typescript
 66 |   const MyComponent: FC<Props> = ({ array, condition }) => {
 67 |     return (
 68 |       <div>
 69 |         <ul>
 70 |           {array.map((item) => (
 71 |             <li key={item}>{item}</li>
 72 |           ))}
 73 |         </ul>
 74 |         {condition ? <div /> : <section />}
 75 |       </div>
 76 |     );
 77 |   };
 78 |   ```
 79 |   В редких случаях, когда ваш рендер зависит от сложного условия или цепочки условий, что приводит к плохой читабельности или вложенным условным операторам `?`, лучше вынести такой код в функцию, в которой описать логику c использованием `if`. И затем вызвыть эту функцию в `return`. Такие функции должны быть в самом низу перед `return`, ниже чем вызовы `useEffect` (исключение для [1.3](#1.3)).
 80 | 
 81 | <a name="1.5"></a>
 82 | 
 83 | - [1.5](#1.5) Не объявляйте константы и функции-хелперы внутри компонента. Код компонента выполняется на каждом рендере, следовательно это лишние вычисления по созданию новых переменных на каждом рендере. Выносите их за пределы компонента, создавая файлы (напр. `constants`/`helpers`/`utils`/`helperName`) рядом с самим компонентом, если они специфичны для него или в более общее место (обычно это папка `shared`), если они могут использоваться где-то ещё.
 84 | 
 85 |   Плохо:
 86 |   ```typescript
 87 |   const MyComponent: FC<Props> = ({ ... }) => {
 88 |     const DAYS_IN_WEEK = 7;
 89 | 
 90 |     const calculateSomeValue = () => { ... };
 91 | 
 92 |     return ( ... );
 93 |   };
 94 |   ```
 95 |   Хорошо:
 96 |   ```typescript
 97 |   // Константы здесь рядом с компонентом для примера, их надо вынести в отдельные файлы.
 98 |   const DAYS_IN_WEEK = 7;
 99 | 
100 |   const calculateSomeValue = () => { ... };
101 | 
102 |   const MyComponent: FC<Props> = ({ ... }) => {
103 |     return ( ... );
104 |   };
105 |   ```
106 | 
107 | <a name="1.6"></a>
108 | 
109 | - [1.6](#1.6) Не забываем про хорошие практики компонентного подхода, описанные в разделе CSS [4.4-4.6](https://github.com/fullstack-development/front-end-best-practices/tree/master/CSS#4.4)
110 | 
111 | <a name="2"></a>
112 | 
113 | ## Пропсы
114 | 
115 | <a name="2.1"></a>
116 | 
117 | - [2.1](#2.1) Пропсы компонента объявлять перед компонентом в том же файле. Это позволит не переключаться между файлами при чтении и беглом просмотре компонента. 
118 | 
119 | <a name="2.2"></a>
120 | 
121 | - [2.2](#2.2) Именовать пропсы компонента словом `Props`. Более подробное имя для пропсов не требуется, из контекста и так понятно, что это пропсы для текущего компонента.
122 | 
123 | <a name="2.3"></a>
124 | 
125 | - [2.3](#2.3) Если ваш компонент предполагает обязательное использование пропа `children`, явно объявите его в `Props` и сделайте обязательным. Если `children` необязательный, можно воспользоваться вспомогательным встроенным типом `PropsWithChildren<Props>`.
126 | 
127 | <a name="2.4"></a>
128 | 
129 | - [2.4](#2.4) Не экспортируйте пропсы компонента без причины. Во первых это засоряет подсказки редактора кода, во вторых неясно, эти пропсы действительно где-то используются или нет. Экспортируйте только если они используются где-то ещё. При экспорте пропсам следует дать более осмысленное имя, добавив название компонента в начало: 
130 |   ```typescript
131 |   export { type Props as MyComponentProps };
132 |   ```
133 |   Примечание: правило применимо, если вы пропсы объявляете в том же файле, что и сам компонент.
134 | 
135 | <a name="2.5"></a>
136 | 
137 | - [2.5](#2.5) Порядок указания пропсов должен быть следующим:
138 | 
139 |   1. Все обязательные пропы-React компоненты
140 | 
141 |   2. Все необязательные пропы-React компоненты
142 | 
143 |   3. Все обязательные значения.
144 | 
145 |   4. Все необязательные значения.
146 | 
147 |   5. Все обязательные функции.
148 | 
149 |   6. Все необязательные функции.
150 | 
151 |   Все необязательные пропсы-значения должны иметь значение по умолчанию.
152 |   
153 |   Если в проекте нет других соглашений, для типов функций используется синтаксис `func(): type`, а не `func: () => type`.
154 | 
155 |   Пример:
156 |   ```tsx
157 |   type Props = {
158 |     Content: FC;
159 |     Icon?: FC;
160 |     size: 'm' | 'l';
161 |     color?: 'primary' | 'secondary' | 'inherit';
162 |     useIsActive(): boolean;
163 |     onClick?(): void;
164 |   }
165 | 
166 |   const MyComponent: FC<Props> = ({ Content, Icon, size, color = 'inherit', useIsActive, onClick }) => {...}
167 |   ```
168 | 
169 | 
170 | <a name="2.6"></a>
171 | 
172 | - [2.6](#2.6) Пропсы компонента, относящиеся к обработке событий, должны именоваться по шаблону `onEventName`, где `EventName` — имя обрабатываемого события.
173 | 
174 | <a name="3"></a>
175 | 
176 | ## Иконки
177 | 
178 | Данный раздел основан на [докладе](https://www.youtube.com/watch?v=7P99kvUDVdU) Петра Жемчугова с HolyJS.
179 | 
180 | Существует множество [способов](https://youtu.be/7P99kvUDVdU?si=Yzjkw7C_FfZYpZnv&t=829) отобразить иконку на странице, каждый из них имеет свои преимущества и недостатки. Наиболее оптимальным же способом на данный момент является использование CSS свойства `mask-image`:
181 | 
182 | <a name="3.1"></a>
183 | 
184 | - [3.1](#3.1) Реализация компонента
185 | 
186 | ```tsx
187 | type Icon24Props = {
188 |   name: "arrow-left" | 'check';
189 |   size: 24;
190 | }
191 | type Icon16Props = {
192 |   name: "arrow-down" | 'arrow-up' | 'check';
193 |   size: 16;
194 | }
195 | // TIP: необходимость разделить иконки по размерам вызвана тем, что хоть svg и масштабируется, но делает оно это линейно: при изменении размеров какие-то линии уже изменили размер, какие-то еще нет -> полоска в 1px при сужении или плохо детализированное изображение при расширении будут плыть и выглядеть не очень хорошо, особенно на retina мониторах.
196 | type Props = Icon24Props | Icon16Props;
197 | 
198 | // TIP: если у вас нет строгой дизайн-системы с фиксированным набором иконок фиксированного размера, то вы можете регулировать конечные размеры во внешних компонентах. Данный подход является плохой практикой так как это значительно ухудшает поддержку кода из-за отсутствия прозрачного набора состояний компонента, но в реальной жизни может рассматриваться как вариант к применению, но только с пониманием ограничений(качество отображения) и дальнейших проблем(усложняется поддержка). Задавать size просто number не рекомендуется так как это нарушит типизацию иконок с фиксированным размером и сделает значение еще менее конкретным.
199 | // type IconStretchProps = {
200 | //   name: Icon16Props['name'] | Icon24Props['name'];
201 | //   size: 'stretch' // или другое название, которые считаете более точным
202 | // }
203 | 
204 | const Icon: FC<Props> = ({ name, size }) => {
205 |   const style = { maskImage: `url(https://<some-cdn-url>/icons/${name}-${size}.svg)` };
206 | 
207 |   return (
208 |     <i className={`icon icon_size_${size}`} style={style} />
209 |   )
210 | }
211 | ```
212 | 
213 | ```scss
214 | .icon {
215 |   display: inline-block;
216 |   // TIP: может быть и градиентом при необходимости
217 |   background: currentColor;
218 |   mask-position: center center;
219 | 
220 |   &_size {
221 |     &_16 {
222 |       width: 16px;
223 |       height: 16px;
224 |     }
225 | 
226 |     &_24 {
227 |       width: 24px;
228 |       height: 24px;
229 |     }
230 | 
231 |     &_stretch {
232 |       width: 100%;
233 |       height: 100%;
234 |     }
235 |   }
236 | }
237 | ```
238 | 
239 | <a name="3.2"></a>
240 | 
241 | - [3.2](#3.2) Использование с другими компонентами:
242 | 
243 | ```tsx
244 | // Лучше чем <Button leftIcon={<IconHeader24/>} /> или <Button LeftIcon={Button.IconHeader24} /> так как не требует создания компонента-обертки вида const IconHeader24 = () => { return <Icon size="heart" size={24} /> } и не позволяет пробросить недокументированный компонент. Размер иконки в данном случае выбирается в самом компоненте Button и наличие файла иконки с нужным размером гарантируется на уровне типов в компоненте Icon.
245 | <Button leftIcon="heart" />
246 | ```
247 | 
248 | <a name="3.3"></a>
249 | 
250 | - [3.3](#3.3) Весь процесс выгрузки иконок в проект можно автоматизировать, [как](https://youtu.be/7P99kvUDVdU?si=EshWFQZBLgIa1Yee&t=1216).
251 | 
252 | <a name="3.4"></a>
253 | 
254 | - [3.4](#3.4) Подводные камни:
255 |   - `mask-image`, в отличии от простого `src`, подвержен CORS, решение: указать на сервере, на котором хранятся ваши картинки, следующие заголовки:
256 |     - `access-control-allow-origin: <ваш домен>`
257 |     - `Access-Control-Max-Age: <время кеширования, например 86400>`
258 |   - кеширование, можно использовать одну из стратегий:
259 |     - с версионированием иконок:
260 |       - добавить версию в имя иконки: в само название или как параметр в url
261 |       - указать заголовок `Cache-Control: max-age=31536000, immutable`, чтобы предотвратить проверку на 100 лет вперед
262 |     - без версионирования иконок, - указать заголовки:
263 |       - `Cache-Control: max-age=86400, must-revalidate`
264 |       - `ETag "<некоторый хеш>"`
265 |   - до появления иконки проходит некоторое время пока изображение не скачено, такое поведение может быть иногда нежелательным, например для показа лоадера, возможные решения:
266 |     - если иконка используется повсюду на сайте, - скачивать всегда. Не подходит как вариант по умолчанию так как будет увеличиваться время time to interact;
267 |     - использовать префетчинг(обычно, браузеры делают это за нас оптимальным образом: например загружают изображение только тогда, когда пользователь проскроллил до нужного места).
268 | 
269 | <a name="4"></a>
270 | 
271 | ## SVG
272 | 
273 | <a name="4.1"></a>
274 | 
275 | - [4.1](#4.1) Во многих фреймворках встроен SVGR, который позволяет подключать svg-файлы как реакт-компоненты. Проблема в том, что у такого компонента напрочь отсутствует типизация, ему можно передать любые пропсы. Решить эту проблему можно следующим образом:
276 |   1. создайте файл `global.d.ts.` со следующим содержимым:
277 | 
278 |       ```ts
279 |         declare module '*.svg' {
280 |         import React from 'react';
281 | 
282 |         export const ReactComponent: React.FC<
283 |           React.SVGProps<SVGSVGElement> & { title?: string }
284 |         >;
285 | 
286 |         const src: string;
287 |         export default src;
288 |       }
289 |       ```
290 | 
291 |   2. Добавьте путь к файлу в массив `include` в вашем `tsconfig.json` (в примере файл находится в корне проекта):
292 |   ![image](https://user-images.githubusercontent.com/90761929/222449468-db502f0b-1997-445a-91b9-e9ee8e96d8ee.png)
293 |   3. Далее при импорте svg - файла вам надо будет писать:
294 | 
295 |       ```ts
296 |         import { ReactComponent as FooImage } from './images/foo.svg';
297 |         import { ReactComponent as BarImage } from './images/bar.svg';
298 |       ```
299 | 
300 |       Но эту запись можно улучшить:
301 |       1. Создайте папку `<Foo>` в директории `images` и внутри поместите файл `index.ts` примерно следующего содержания:
302 | 
303 |           ```ts
304 |           import { 
305 |             default as normalSrc,
306 |             ReactComponent as NormalComponent,
307 |           } from './default.svg';
308 |           import { 
309 |             default as largerSrc,
310 |             ReactComponent as LargerComponent,
311 |           } from './larger.svg';
312 |           import {
313 |             default as smallerSrc,
314 |             ReactComponent as SmallerComponent,
315 |           } from './smaller.svg';
316 | 
317 |           // TIP: должно импортироваться из общего места хранения типов
318 |           type Icon =  {
319 |             src: string;
320 |             Component: React.FC<
321 |               React.SVGProps<SVGSVGElement> & { title?: string }
322 |             >;
323 |           };
324 | 
325 |           const normal: Icon = {
326 |             src: normalSrc,
327 |             Component: NormalComponent,
328 |           };
329 | 
330 |           const larger: Icon = {
331 |             src: largerSrc,
332 |             Component: LargerComponent,
333 |           };
334 | 
335 |           const smaller: Icon = {
336 |             src: smallerSrc,
337 |             Component: SmallerComponent,
338 |           };
339 | 
340 |           export { normal, larger, smaller }
341 |           ```
342 | 
343 |       2. Создайте файл `index.ts` в папке `images` и сделайте там реэкспорт ваших иконок-модулей:
344 | 
345 |           ```ts
346 |             export * as FooImage from './Foo';
347 |           ```
348 | 
349 |       Теперь у вас будет красивый импорт и типизированные svg:
350 | 
351 |       ```tsx
352 |         import { FooImage } from './images';
353 | 
354 |         <FooImage.larger.Component />
355 |         <img src={FooImage.smaller.src} />
356 |       ```
357 | 
358 | <a name="5"></a>
359 | 
360 | ## Экспорт
361 | 
362 | <a name="5.1"></a>
363 | 
364 | - [5.1](#5.1) Именованный экспорт предпочтительней дефолтного. Именованный экспорт заставляет нас использовать правильное имя при импорте, исключая возможность написания любого имени или банально опечатки. Особенно неприятно, если одна и та же сущность в разных местах импортируется с разными именами. С именованными импортами за этим не нужно следить.
365 | 
366 | <a name="5.2"></a>
367 | 
368 | - [5.2](#5.2) Используйте реэкспорт. Например в корне папки `components` создайте `index.ts` файл и экспортируйте в нём все необходимые компоненты:
369 |   ```typescript
370 |   // src/components/index.ts
371 | 
372 |   // Если вы используйете именованный экспорт
373 |   export { MyComponent } from './MyComponent';
374 |   // Если вы используете дефолтный экспорт
375 |   export { default as MyComponent} from './MyComponent';
376 |   ```
377 |   Это позволит при импорте делать запись следующего вида:
378 |   ```typescript
379 |   // Было
380 |   import { MyComponent1 } from 'shared/components/MyComponent1';
381 |   import { MyComponent2 } from 'shared/components/MyComponent2';
382 |   import { MyComponent3 } from 'shared/components/MyComponent3';
383 |   // Стало
384 |   import { MyComponent1, MyComponent2, MyComponent3 } from 'shared/components';
385 |   ```
386 |   Во первых в большинстве случаев это сокращает запись импортов. Во вторых так проще следить за [порядком импортов](../JS/README.md#1.17), так как у вас теперь меньше вложенности. В третьих вы явно декларируете, что можно импортировать из той или иной папки. У вас появляется "точка входа". Не всегда все компоненты, утилиты и т.д. должны экспортироваться наружу. Часть из них может быть предназначена для внутреннего пользования. Типичные случаи для реэкспорта: папки `components`, `icons`, `utils`, `hooks`, `features/featureName`, и т.д.
387 |   
388 |   Если вам нужно просто прокинуть реэкспорт из вложенной папки (со своим `index.ts`) на уровень выше, можно воспользоваться синтаксисом:
389 |   ```typescript
390 |   export * from './folderName';
391 |   ```
392 | 
393 | <a name="6"></a>
394 | 
395 | ## Переменные окружения
396 | 
397 | <a name="6.1"></a>
398 | 
399 | - [6.1](#6.1) Если в вашем проекте используются переменные окружения, например файл `.env`, создайте файл `.env.example`, который попадёт в индексацию git. Перечислите в нём все переменные окружения, но без их значений. Так будет понятно, какое ожидается содержимое `.env` файла для работы проекта. Для большей ясности можно указать тип переменной (не забывая, что все переменные окружения изначально строки), например: 
400 |   ```
401 |   NEXT_PUBLIC_API_URL=string
402 |   NEXT_PUBLIC_IS_TESTNET=boolean
403 |   NEXT_PUBLIC_TRANSACTION_FEE=number
404 |   ```
405 | 
406 | - [6.2](#6.2) Вынесите переменные окружения в отдельный объект, например:
407 |   ```typescript
408 |   // shared/constants/environment.ts
409 |   export const environment = {
410 |     apiUrl: process.env.NEXT_PUBLIC_API_URL,
411 |     isTestnet: process.env.NEXT_PUBLIC_IS_TESTNET,
412 |     transactionFee: process.env.NEXT_PUBLIC_TRANSACTION_FEE
413 |   };
414 |   ```
415 |   По умолчанию `process.env` никак не типизирован и даёт возможность обратиться к чему угодно. Это неудобно при обращении к переменным окружения. Приходится либо писать переменную по памяти (где легко ошибиться), либо копировать - вставить. Обращаясь к переменным окружения только в одном месте, вы сужаете все потенциальные ошибки до этого места. Там же можно выполнить предварительную обработку при необходимости, сделать приведение типа один раз вместо того, что бы делать это везде, где используется переменная. Так же запись вида `environment.apiUrl` куда приятнее, чем `process.env.NEXT_PUBLIC_API_URL`. 
416 | 
417 |   В качестве альтернативы, если вы не хотите создавать отдельный объект, можно [типизировать](https://stackoverflow.com/questions/45194598/using-process-env-in-typescript) сам `process.env`.
418 | 
419 | <a name="7"></a>
420 | 
421 | ## Работа с API
422 | 
423 | <a name="7.1"></a>
424 | 
425 | - [7.1](#7.1) Поместите функции по работе с API в папку `api`, структурируйте её. Будь-то обычный `fetch` или использование `axios` с его конфигом, интерсепторами, пр. Там же могут лежать и типы ответов на запросы. Затем вызывайте эти функции в стейт менеджере, компонентах, где либо ещё. Так у вас в одном месте будет вся работа с api. Вот пример одной из возможных структур с использованием `axios`:
426 |   ```
427 |   api
428 |   ├── controllers
429 |   │   ├── feedback             
430 |   │   │   ├── converters    # папка с конвертерами для данных запросов
431 |   │   │   ├── controller.ts # содержит функции get, post, delete для /feedback   
432 |   │   │   ├── index.ts      # реэкспорт
433 |   │   │   ├── types.ts      # типы для данных запросов     
434 |   ├── config.ts     # конфиг axios
435 |   ├── core.ts       # интерсепторы axios
436 |   ├── helpers.ts 
437 |   ``` 
438 |   Исключения: использование библиотек, предлагающих свою структуру организации работы с API. Например таких как `rtk-query`.
439 | 
440 | <a name="8"></a>
441 | 
442 | ## Общие принципы работы со стейт менеджерами
443 | 
444 | Если у вас в проекте **нет явной архитектуры**:
445 | 
446 | <a name="8.1"></a>
447 | 
448 | - [8.1](#8.1)  Cтарайтесь разделять стейт по функционалу. Не пихайте всё в один стейт. Если вы используете стейт менеджер для запросов к API, возможно вам поможет структура сущностей бэкенда - users, rooms, orders, auth.
449 | 
450 | <a name="8.2"></a>
451 | 
452 | - [8.2](#8.2) Если вы используете стейт менеджер для запросов к API, делайте все запросы через стейт менеджер. Даже если они никак не взаимодействуют со стейтом (напр. это может быть POST-запрос, который ничего не возвращает). Нужно это для однообразия, что бы не было так, что часть компонентов делают запросы напрямую, а часть через диспатч. 
453 | 
454 | <a name="9"></a>
455 | 
456 | ## Оптимизация
457 | 
458 | - В интернете есть множество материалов про [преждевременную оптимизацию](https://habr.com/ru/companies/ruvds/articles/465809/) и чем она вредна. Помните об этом. 
459 | - Если ваш код работает некорректно без оптимизации, а с оптимизацией проблема уходит, то вам стоит в первую очередь устранить проблему, и только потом оптимизировать. 
460 | - Мы же хотим поговорить про особенности рендеринга React приложений и частые кейсы, из-за которых ваше приложение может начать тормозить. У нас есть крайне полезный [топик](./Optimization.md), посвящённый некоторым оптимизациям при разработке React-приложений.
461 | 
462 | <a name="10"></a>
463 | 
464 | ## Общее
465 | 
466 | <a name="10.1"></a>
467 | 
468 | - [10.1](#10.1) Не создавайте не нужных `.tsx` файлов. Если в таком файле нет JSX кода, он должен иметь расширение `.ts`.
469 | 


--------------------------------------------------------------------------------