Skip to content

Latest commit

 

History

History
89 lines (82 loc) · 5.31 KB

1.md

File metadata and controls

89 lines (82 loc) · 5.31 KB

Раздел 1. Комментарии в коде

На совместных хакатонах было принято решение по комментариям в проекте, из них было выделено 2 основных пункта, когда и как комментировать код.
Комментарии в коде пишем только на английском языке

1.1 Комментарии в стилях

В стилях комментируем только неочевидные css свойства, неочевидные зависимости.

1.1.1 Пример не очевидного css свойства

В примере возьмем случай обрезки картинки родительским блоком. В данном варианте свойство transform: translateZ(0); исправляет баг с отображением border-radius. В Webkit браузерах при взаимодействии с другими элементами может пропадать border-radius у блоков с overflow: hidden.

.some-block {
 position: relative;
 width: 50px;
 height: 50px;
 overflow: hidden;
 transform: translateZ(0);
 border-radius: 50%;
}

.some-block__img {
 position: absolute;
 top: 0;
 left: 0;
 width: 100%;
 height: auto;
}

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

.some-block {
 overflow: hidden;
 transform: translateZ(0); /* fix render bug with overflow: hidden elements in webkit */
}

1.1.2 Пример не очевидной зависимости в css

Бывают случаи когда нужно в коде сделать возможность легко изменить высоту header и nav и что бы контент подтянулся сам после изменения высоты header и nav. Или же nav нужно вообще скрыть. Рассмотрим пример где есть зависимость высоты основного контента от высоты header и nav.

файл variables.css:

:root {
 --header-height: 100px; /* this variable used in files: header.css , layout.css */
 --nav-height: 50px; /* this variable used in files: nav.css , layout.css */
}

файл header.css:

.header {
 height: var(--header-height); /* you can change it in variables.css */
}

файл nav.css:

.nav {
 height: var(--nav-height); /* you can change it in variables.css */
}

файл layout.css:

.layout {
 height: calc(var(--header-height)+var(--nav-height)); /* you can change it in variables.css */
}

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

1.2 Комментарии в templates

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

1.2.1 Local team

При работе с локальной командой, мы не пишем комментарии в templates, у нас в работе используется JIRA , где у задачи описаны критерии её выполнения, требования.
Как работает блок и какие имеет классы мы описываем в шапке самой задачи в блоке "Description".
Комментарии можно писать на русском или английском языке.

Блок .some-block может принимать 2 статуса  
.some-block--error: цвет текста красный   
.some-block--success: цвет текста зеленый  
Стандартный цвет текста серый

1.2.2 Remote team

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

Пример:

<!-- Block header start -->
<!-- Block header states: header--fixed -->
<header class="header">
  <!-- header content -->
</div>
<!-- Block header end -->