From f2b23f6e826d777c4b26639f3f6f0fdc0d23ed4b Mon Sep 17 00:00:00 2001 From: Sasha Sushko Date: Fri, 4 Feb 2022 10:07:23 +0300 Subject: [PATCH] =?UTF-8?q?temp:=20=D0=B7=D0=B0=D0=B1=D1=8D=D0=BA=D0=B0?= =?UTF-8?q?=D0=BF=D0=B8=D1=82=20=D1=82=D0=B5=D0=BA=D1=81=D1=82=D1=8B=20?= =?UTF-8?q?=D1=81=D1=82=D0=B0=D1=80=D1=8B=D1=85=20=D0=BA=D1=80=D0=B8=D1=82?= =?UTF-8?q?=D0=B5=D1=80=D0=B8=D0=B5=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- temp/1-variable.md | 84 ++++++++++++++++++++++++++++++++ temp/2-collection.md | 39 +++++++++++++++ temp/3-function.md | 67 ++++++++++++++++++++++++++ temp/4-constant.md | 14 ++++++ temp/5-component.md | 100 +++++++++++++++++++++++++++++++++++++++ temp/6-special-fields.md | 7 +++ 6 files changed, 311 insertions(+) create mode 100644 temp/1-variable.md create mode 100644 temp/2-collection.md create mode 100644 temp/3-function.md create mode 100644 temp/4-constant.md create mode 100644 temp/5-component.md create mode 100644 temp/6-special-fields.md diff --git a/temp/1-variable.md b/temp/1-variable.md new file mode 100644 index 0000000..6f26e8f --- /dev/null +++ b/temp/1-variable.md @@ -0,0 +1,84 @@ +# Переменные названы по-английски, в единственном числе + + + + + + +К переменным относятся свойства классов и объектов, параметры функций. Словосочетания допустимы: + +```js +const mascotName = 'Кекс'; + +const rectangle = { + width: 10, + length: 3, + height: 5 +}; + +function calculateRectangleSquare (width, length) { + return width * length; +} +``` + +Для длинных слов можно использовать общепринятые сокращения: `cb` для единственного параметра-колбэка, `evt` для объектов события `Event`, `err` для объектов ошибок `Error`, `src`, `img`, `btn` и так далее. + +Допускается использование «своих» сокращений, если они будут понятны проверяющему без объяснений. + +_Например,_ сокращённое название `calcRectSquare` вместо `calculateRectangleSquare`: + +```js +function calcRectSquare (width, length) { + return width * length; +} +``` + +Слова `calculate` и `Rectangle` сокращены до `calc` и `Rect` соответственно. Но что делает функция по-прежнему понятно, а название стало короче. + +А вот попытки сократить название функции ещё нарушат критерий, потому что сокращения вроде `calcRSquare`, `calcRectSq`, `cRectSquare` или `cRS` нельзя однозначно разгадать. + +**Обратите внимание,** в циклах и цикличных методах можно использовать однобуквенные переменные `i`, `j`, `k`, `l` для индексов. + +## Почему нужно соблюдать этот критерий? + +Сперва про английский язык. Всё просто — это стандарт. Разработчики во всём мире используют английский язык. Вы можете «встать в позу» и в своём проекте использовать транслит, код будет работать, но коллеги не оценят. В особенности иностранные коллеги. Если вы пока не знаете английский язык, пользуйтесь онлайн-переводчиком. Это нормально. + +Теперь о сокращениях. Код читают программисты, компьютер лишь выполняет его. Все эти «читаемые имена» переменных нужны людям, и код вы пишете для людей. Относитесь к требованиями по именованию как к грамматике языка программирования. То, как разработчик следуюет требованиям, показывает насколько он образован. + +Сравните транслит: + +```js +const kvadrat = { + dlina: 10, + shirina: 3, + visota: 5 +}; + +function poschitatPloschadKvadrata (dlina, shirina) { + return dlina * shirina; +} +``` + +С английским языком: + +```js +const rectangle = { + width: 10, + length: 3, + height: 5 +}; + +function calcRectSquare (width, length) { + return width * length; +} +``` + +Какой код проще читать? Думаю, ответ очевиден. + +А теперь представьте, что разработчик не только пишет транслитом, но и сокращает имена: `pschttPlschdKvdrt`... Б-р-р. + +Поначалу требования могут казаться странными. Это пройдёт, как только вам нужно будет разобраться в чужом коде, который игнорирует все требования. А разработчики гораздо чаще читают код, чем пишут. Причём чужой. + +--- + +Правило «если сокращения будут понятны проверяющему без объяснений» не означает, что можно завернуть код студента по критерию, потому что вы привыкли использовать другое сокращение или полную форму слова. Если вам понятно, что кроется за именем переменной, критерий соблюдён. diff --git a/temp/2-collection.md b/temp/2-collection.md new file mode 100644 index 0000000..758997b --- /dev/null +++ b/temp/2-collection.md @@ -0,0 +1,39 @@ +# Переменные, содержащие коллекции, именуются во множественном числе + +Неправильно: + +```js +const age = [12, 40, 22, 7]; +const name = ['Иван', 'Петр', 'Мария', 'Алексей']; + +const wizard = { + name: 'Гендальф', + friend: ['Саурон', 'Фродо', 'Бильбо'] +}; + +const listItem = document.querySelectorAll('ul li'); +``` + +Правильно: + +```js +const ages = [12, 40, 22, 7]; +const names = ['Иван', 'Петр', 'Мария', 'Алексей']; + +const wizard = { + name: 'Гендальф', + friends: ['Саурон', 'Фродо', 'Бильбо'] +}; + +const listItems = document.querySelectorAll('ul li'); +``` + +**Обратите внимание,** что слово `data` — это множественное число от слова `datum`, поэтому его использование в качестве имени переменной для массива корректно. + +## Почему нужно соблюдать этот критерий? + +Коллекции в JavaScript можно перебирать в циклах. Если правило соблюдается, удобно понять, что по переменной можно ситерироваться, даже не глядя в место объявления: + +```js +listItems.forEach(() => {}); +``` diff --git a/temp/3-function.md b/temp/3-function.md new file mode 100644 index 0000000..e9c669f --- /dev/null +++ b/temp/3-function.md @@ -0,0 +1,67 @@ +# Функции именуются с глагола + +Название функции или метода должно быть глаголом и соответствовать действию, которое выполняет функция или метод. Например, можно использовать глагол `get` для функций и методов, которые что-то возвращают. + +Неправильно: + +```js +const action = function (names) { + names.forEach((name) => { + console.log(name); + }); +}; + +const wizard = { + name: 'Гендальф', + action() { + console.log('Стреляю файрболлом!'); + } +}; + +const randomNumber = () => Math.random(); +``` + +Правильно: + +```js +const printNames = function (names) { + names.forEach((name) => { + console.log(name); + }); +}; + +const wizard = { + name: 'Гендальф', + shoot() { + console.log('Стреляю файрболлом!'); + } +}; + +const getRandomNumber = () => Math.random(); +``` + +_Кстати,_ функции-предикаты — функции, которые возвращают булево значение — удобно именовать по схеме «`is` + признак»: + +```js +function checkValueToNull(value) { // правильно + return value === null; +} + +function isNull(value) { // тоже правильно + return value === null; +} +``` + +Предикаты, которые нельзя назвать с `is`, можно именовать с `has`: + +```js +function hasOddNumber(values) { + return values.some(() => {}); +} +``` + +**Важно!** Из правила существуют исключения: геттеры и сеттеры, редьюсеры. + +## Почему нужно соблюдать этот критерий? + +Отличие функции от обычной переменной, что функцию можно вызвать. Удобно, когда это понятно из названия, и не нужно искать объявление. diff --git a/temp/4-constant.md b/temp/4-constant.md new file mode 100644 index 0000000..84cb770 --- /dev/null +++ b/temp/4-constant.md @@ -0,0 +1,14 @@ +# Константы записываются в нотации `UPPER_SNAKE_CASE` + +Слова разделяются подчёркиваниями: + +```js +const MAX_HEIGHT = 400; +const EARTH_RADIUS = 6370; +``` + +**Обратите внимание,** константа - это постоянное значение, а не всё, что объявлено через `const`. + +## Почему нужно соблюдать этот критерий? + +Константы показывают, что значение переменной не изменяется по ходу выполнения программы. Надёжно и удобно знать это заранее. diff --git a/temp/5-component.md b/temp/5-component.md new file mode 100644 index 0000000..07c3f2e --- /dev/null +++ b/temp/5-component.md @@ -0,0 +1,100 @@ +# Классы, функции-конструкторы, компоненты и перечисления записываются в нотации `PascalCase` + +`PascalCase` означает, что название начинается заглавной буквы. + +Неправильно: + +```js +// Функция-конструктор +const wizard = function (name, age) { + this.name = name; + this.age = age; +}; + +// Функция +const Fly = function (coordinate) { + console.log(`Смотрите, я лечу вон туда ${coordinate}!`); +}; + +// Перечисление +const statusCodes = { + ok: 200, + notFound: 404, + badRequest: 400, +}; + +// Перечисление +const STATUS_CODE = { + Ok: 200, + NotFound: 404, + BadRequest: 400, +}; + +// Класс +class wizard { + constructor(name, age) { + this.name = name; + this.age = age; + } +} + +// Класс +class Run { + constructor() { + console.log('О, я бегу!'); + } +} +``` + +Правильно: + +```js +// Функция-конструктор +const Wizard = function (name, age) { + this.name = name; + this.age = age; +}; + +// Функция +const fly = function (coordinate) { + console.log(`Смотрите, я лечу вон туда ${coordinate}!`); +}; + +// Перечисление +const StatusCode = { + OK: 200, + NOT_FOUND: 404, + BAD_REQUEST: 400, +}; + +// Класс +class Wizard { + constructor(name, age) { + this.name = name; + this.age = age; + } +} + +// Класс +class Runner { + constructor() { + console.log('О, я бегун!'); + } +} +``` + +Названия функций, не являющихся конструкторами, должны начинаться со строчной буквы. + +**Обратите внимание,** что не все объекты в коде проекта должны быть перечислениями. Допускается использование объектов в качестве словарей: + +```js +const priceTypeToRange = { + low: 'до 200 ₽', + medium: 'от 200 ₽ до 500 ₽', + high: 'от 500 ₽', +}; +``` + +## Почему нужно соблюдать этот критерий? + +Так принято? diff --git a/temp/6-special-fields.md b/temp/6-special-fields.md new file mode 100644 index 0000000..b567e4e --- /dev/null +++ b/temp/6-special-fields.md @@ -0,0 +1,7 @@ +# Имена защищённых полей начинаются с подчёркивания, приватных — с решётки + +Свойства и методы, которые есть в классе, но не предназначены для внешнего использования, помечаются как приватные — их названия начинаются с решётки `#`. Свойства и методы, которые не предназначены для внешнего использования, но используются дочерними классами, помечаются как защищённые — их названия начинаются с подчёркивания `_`. Доступ к таким полям извне класса запрещён. + +## Почему нужно соблюдать этот критерий? + +Так принято?