ARUI Feather — это единая библиотека визуальных компонентов Альфа Банка.
Следующие базовые принципы разработки лежат в основе кода ARUI Feather.
Максимально простой код с низком порогом входа.
Все публичные интерфейсы библиотеки покрыты документацией. Старайтесь придерживаться этой доброй традиции при добавлении/изменение публичных фичей.
Всегда описывайте предназначение компонента в формате JSDoc.
// Good
/**
* Компонент текстового поля ввода.
*/
class Input extends React.Component {
...
}
// Bad
class Input extends React.Component {
...
}
Используйте для документирования формат React.propTypes совместно с комментарием в JSDoc.
// Good
type InputProps = {
/**
* Размер компонента
*/
size?: 's' | 'm' | 'l' | 'xl';
}
class Input extends React.Component<InputProps> {
}
// Bad
type InputProps = {
size?: 's' | 'm' | 'l' | 'xl';
}
class Input extends React.Component<InputProps> {
}
Используйте defaultProps для задания значений по умолчанию.
// Good
type InputProps = {
/**
* Размер компонента
*/
size?: 's' | 'm' | 'l' | 'xl';
}
class Input extends React.Component<InputProps> {
static defaultProps = {
size: 'm'
};
render() {
return <div className={ this.props.size } />
}
}
// Bad
type InputProps = {
/**
* Размер компонента
*/
size?: 's' | 'm' | 'l' | 'xl';
}
class Input extends React.Component<InputProps> {
render() {
return <div className={ this.props.size || 'm' } />
}
}
Используйте неглагольные фразы для описания атрибутов.
// Good
type InputProps = {
/**
* Размер компонента
*/
size?: 's' | 'm' | 'l' | 'xl';
}
// Bad
type InputProps = {
/**
* Определяет размер компонента
*/
size?: 's' | 'm' | 'l' | 'xl';
}
Используйте модификаторы доступа явно
// Good
class Input extends React.Component {
/**
* Ставит фокус на поле ввода.
*/
public focus() {
...
}
}
// Bad
class Input extends React.Component {
/**
* Ставит фокус на поле ввода.
*/
focus() {
...
}
}
При написании документации к функции/методу начинайте предложение с глагола в третьем лице.
// Good
/**
* Ставит фокус на поле ввода.
*/
function focus() {
...
}
// Bad
/**
* Устанавливаем фокус на поле ввода.
*/
function focus() {
...
}
Всегда описывайте ввод/вывод функции/метода.
// Good
/**
* Устанавливает опорный элемент.
* Возвращает предыдущий опорный элемент.
*
* @param target Новый опорный элемент.
*/
function setTarget(target: HTMLElement): HTMLElement {
...
return oldTarget;
}
// Bad
/**
* Устанавливает опорный элемент.
*/
function setTarget(target) {
...
return oldTarget;
}
Все публичные интерфейсы библиотеки покрыты unit тестами. Тесты в библиотеке пишутся с условием наличия настоящего DOM.
- Поведение внешних атрибутов, заданных через Props.
- Поведение внешних публичных методов, размеченных как
public. - Поведение внешних обработчиков, заданных через Props
Убедитесь, что внешние атрибуты корректно аффектят на генерацию DOM компонента. Для этого стоит использовать chai-dom.
Вызов внешних методов, как правило, приводит к изменению DOM компонента и/или вызову внешнего обработчика. Для этого стоит использовать chai-dom и chai-spies.
Для этого стоит использовать chai-spies. Также стоит протестировать, что во внешних обработчиках приходят корректные аргументы.
Для commit messages используйте формат Angular.
В теме сообщения указывайте глагол в настоящем времени, который информирует об изменениях.
Для валидации commit messages на соответствующем git hook используется commitlint.
На основе коммитов в ветке master генерируется CHANGELOG.md.
Поэтому в мастер попадают коммиты только с информативными commit messages.
После окончания работы над задачей и перед вливанием коммитов в ветку master
сосквошьте ваш набор коммитов в один. Это можно сделать, например, так:
git fetch && git rebase -i origin/master- Пометьте коммиты, который вы хотите слить буквой
s. - Укажите commit message:
feat(input): my new feature for input.
// Good
feat(input): add new feature for input
// Bad
feat(input) rename some vars
fix(PR): fix some PR issues
wip
Pull Request (PR) может попасть в master ветку при соблюдении всех условий:
- Если PR реализует новый публичный функционал, то на него написана документация.
- Код в PR соблюдает правила оформления для
tsиcssкода. - Если PR добавляет новые фичи, то на них написаны тесты.
- Если PR изменяет существующее публичное API, то должна соблюдаться Deprecation Policy.
- У PR корректный commit message.
- Два ментора поставили лайк вашему PR.
- PR успешно собрался на CI.
- PR актуален с текущей веткой
master.
Далее контрибьютор мержит PR в master самостоятельно.
Самый простой способ найти менторов, которые проведут review вашего кода -
это посмотреть git blame по тем компонентам, которые вы правите.
Просто добавьте менторов лучше всего знакомых с кодом компонента, который вы правите в вашем Code Review.
Если вы добавляете новый компонент, то можете добавить на Code Review менторов лучше всего знакомых с кодом библиотеки. Список менторов можно найти в package.json.