Код-стайл

Пишите код так, чтобы он был более структурированным и читаемым.

1. Имена каталогов должны быть написаны строчными буквами и разделены дефисами. Например: каталог с именем form-item, а не FormItem.

2. Каждый компонент должен иметь файл index.ts в качестве точки входа, который экспортирует все содержимое компонента. Пример содержимого файла index.tsx для компонента form-item:

export * from './src/hoc';
export * from './src/utils';
export * from './src/components';
export * from './src/createSuperFormItem';

Рекомендуется сортировать экспортируемые элементы по длине, чтобы код выглядел аккуратно.

3. Компоненты React должны использовать стиль именования CamelCase. Например, компонент Color.tsx.

4. Компонентам не следует добавлять префикс «Super». Например, вместо SuperCheckbox.tsx следует использовать Checkbox.tsx.

5. Префикс «Super» должен использоваться для компонентов. Например, Checkbox.tsx соответствует компоненту SuperCheckbox.

6. Для не-React компонентов следует использовать стиль именования snake_case. Например, util.ts или useAxios.ts.

7. Тип компонента React должен быть определен как компонент_имяProps. Например, для компонента SuperCheckbox тип должен быть SuperCheckboxProps.

8. Функции экспорта: максимум 2 аргумента, остальные помещаются в объект опций (options object). При разработке интерфейса функции следуйте следующим правилам:

• Если функция является частью публичного API, она может принимать от 0 до 2 аргументов, и при необходимости можно добавить объект опций, что в сумме составляет не более 3 аргументов.
• Необязательные аргументы обычно должны быть включены в объект опций. Если есть только один необязательный аргумент, который вряд ли будет добавлен в будущем, его можно не включать в объект опций.

Пример неправильного использования необязательных аргументов:

// Ошибка: слишком много аргументов (#1), несколько необязательных аргументов (#2).
export function renameSync(oldName: string, newName: string, replaceExisting?: boolean, followLinks?: boolean) {}

Пример правильного использования:

interface RenameOptions {
  replaceExisting?: boolean;
  followLinks?: boolean;
}
export function renameSync(oldName: string, newName: string, options: RenameOptions = {}) {}

9. Между различными компонентами используйте псевдонимы для импорта.

import { Btns } from '@/btns'; // правильно

import { Btns } from 'super-antd'; // неправильно

import { Btns } from '../btns'; // правильно

10. Разумно используйте JsDoc. Если возможно, лучше всего писать однострочные комментарии JSDoc. Например:

/** Так пишется однострочный комментарий JSDoc. */
export function foo() {
  // ...
}

Не пишите так:

/** Не следует так писать однострочный комментарий JSDoc. */

Строковые литералы кода должны быть заключены в обратные кавычки (`), а не в кавычки. Например:

/** Импортируем что-то из super-antd. */

Используйте @param, поскольку TypeScript уже является строго типизированным.

/**
 * Функция с неочевидным параметром.
 *
 * @param foo Описание неочевидного параметра.
 */

Комментарии к примерам кода должны отделяться пустой строкой, а каждая строка примера должна иметь 6 дополнительных пробелов. Это на 4 пробела больше, чем в первой колонке комментария. Пример:

/**
 * Простой комментарий и пример:
 *
 *     import { useAxios } from 'super-antd';
 *     const { loading } = useAxios({ api });
 */

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

11. Тестовые случаи и файлы должны соответствовать друг другу. У каждого файла должен быть соответствующий тестовый случай, и имена файлов тестовых случаев должны совпадать с именами тестируемых файлов.

src
  btns
    Btns.tsx

# Соответствующий тестовый файл должен называться
tests
  btns
    Btns.test.tsx

12. Примеры документов должны находиться в отдельных файлах. Dumi предоставляет тег code для включения примеров компонентов, поэтому не рекомендуется включать примеры в Markdown. Каждая статья должна иметь соответствующую папку, например:

form.md
select.md

# Их файлы примеров соответствуют папкам того же уровня
__demos__
  form
    hideLabel.tsx
    api_basic.tsx

Имя файла должно отражать основную функцию, например, hideLabel для свойства hideLabel, и api_basic для основного использования свойства api. Вместо этого не следует делать следующее:

❌
__demos__
  form
    demo1.tsx
    demo2.tsx

13. В Typescript используются три типа шаблонов: XxxProps, XxxType и XxxOptions.

• XxxProps используется для свойств React-компонентов.
• XxxxOptions используется для параметров функций.
• XxxxType используется в других случаях.

interface SuperFormProps {
  // ...
}

const SuperForm: FC<SuperFormProps> = () => {};

interface GetBtnsOptions {}
function getBtns(options: GetBtnsOptions) {}

export type AlignType = 'left' | 'right' | 'center'; // В других случаях используется XxxType

interface SuperBtnsProps {
  align: AlignType;
}

Обратите внимание, что если у компонента есть несколько частей, то другие части также должны быть определены с помощью XxxProps.

interface SuperFormItemInjectProps {}
interface SuperFormItemOverwriteProps {}
interface SuperFormItemProps extends SuperFormItemInjectProps, SuperFormItemOverwriteProps {}

14. Используйте useCreation вместо useMemo. Подробнее см. в документации по useCreation.

15. Экспортируйте собственные Props для каждого компонента, чтобы другие могли их использовать в своих обёртках.

16. Если содержимое компонента не может быть размещено в одном файле, создайте каталог src. Например, для компонента provider:

provider
  index.ts # Используется для экспорта всего
  src
    Provider.tsx # должен быть одноимённый
    context.ts

Для содержимого, экспортируемого по умолчанию с помощью export default, также требуется export

export const foo = 123; // даже если это export default, также требуется export
export default foo;

Каждый prop каждого компонента должен иметь комментарий.