shopot / naming-cheatsheet

JavaScript Naming Cheatsheet

Перевод Naming cheatsheet

Шпаргалка по именованию

• Английский язык
• Соглашение об именовании (Naming convention)
• S-I-D
• Избегайте сокращений
• Избегайте дублирования контекста
• Отразить ожидаемый результат
• Именование функций
  • A/HC/LC Pattern
  • Actions
  • Context
  • Prefixes
• Единственное и множественное число

---

Называть вещи сложно. Этот руководство должно помочь сделать это проще.

Хотя эти предложения можно применить к любому языку программирования, я буду использовать JavaScript, чтобы проиллюстрировать их на практике.

Английский язык

Используйте английский язык при именовании переменных и функций.

/* Bad */
const primerNombre = 'Gustavo';
const amigos = ['Kate', 'John'];

/* Good */
const firstName = 'Gustavo';
const friends = ['Kate', 'John'];

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

Соглашение об именовании (Naming convention)

В JavaScript для именования переменных и функций используется camelCase нотация, для классов и функций-конструкторов PascalCase нотация.

/* Bad */
const page_count = 5;
const ShouldUpdate = true;
class appLogger {};

/*  Good */
const pageCount = 5;
const shouldUpdate = true;
class AppLogger {};

S-I-D

Имя должно быть коротким, интуитивным и описательным (short, intuitive, descriptive):

• Короткий. Имя не должно занимать много времени, чтобы набираться и, следовательно, запоминаться;
• Интуитивный. Имя должно читаться естественно, как можно ближе к обычной речи;
• Описательный. Имя должно наиболее эффективно отражать то, что оно делает/чем обладает.

/* Bad */
const a = 5; // "a" может означать что угодно
const isPaginatable = a > 10; // "Paginatable" звучит крайне неестественно
const shouldPaginatize = a > 10; // Придуманные глаголы — это так весело!

/* Good */
const postCount = 5;
const hasPagination = postCount > 10;
const shouldPaginate = postCount > 10; // альтернатива

Избегайте сокращений

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

/* Bad */
const onItmClk = () => {};

/* Good */
const onItemClick = () => {};

Избегайте дублирования контекста

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

class MenuItem {
  /* Bad: Имя метода дублирует контекст (который "MenuItem") */
  handleMenuItemClick = (event) => { ... };

  /* Good: Читается хорошо, как `MenuItem.handleClick()` */
  handleClick = (event) => { ... };
}

Отразить ожидаемый результат

Имя должно отражать ожидаемый результат.

/* Bad */
const isEnabled = itemCount > 3;
return <Button disabled={!isEnabled} />;

/* Good */
const isDisabled = itemCount <= 3;
return <Button disabled={isDisabled} />;

---

Именование функций

A/HC/LC Pattern

Существует полезный шаблон, которому следует следовать при именовании функций:

prefix? + action (A) + high context (HC) + low context? (LC)

Посмотрите, как можно применить этот шаблон, в таблице ниже.

Name	Prefix	Action (A)	High context (HC)	Low context (LC)
getUser		get	User
getUserMessages		get	User	Messages
handleClickOutside		handle	Click	Outside
shouldDisplayMessage	should	Display	Message

Примечание. Порядок контекста влияет на значение переменной. Например, shouldUpdateComponent означает, что вы собираетесь обновить компонент, а shouldComponentUpdate сообщает вам, что comComponent обновит себя, и вы контролируете только когда он должен обновиться. Другими словами, High context (HC) подчеркивает значение переменной.

Actions

Глагольная часть имени вашей функции. Самая важная часть, отвечающая за описание того, что делает функция.

get

Немедленный доступ к данным (т. е. сокращенный метод получения внутренних данных).

function getFruitCount() {
  return this.fruits.length;
}

Смотрите также compose.

Вы также можете использовать get при выполнении асинхронных операций:

async function getUser(id) {
  return await fetch(`/api/user/${id}`);
}

set

Устанавливает переменную декларативным способом со значением A в значение B.

let fruits = 0;

function setFruits(nextFruits) {
  fruits = nextFruits;
}

setFruits(5);

console.log(fruits); // 5

reset

Возвращает переменную в исходное значение или состояние.

const initialFruits = 5;

let fruits = initialFruits;

setFruits(10);

console.log(fruits); // 10

function resetFruits() {
  fruits = initialFruits;
}

resetFruits();

console.log(fruits); // 5

remove

Удаляет что-то _от_куда-то.

Например, если у вас есть коллекция выбранных фильтров на странице поиска, удаление одного из них из коллекции - это removeFilter, а не deleteFilter (и именно так вы, естественно, скажете это и на английском языке):

function removeFilter(filterName, filters) {
  return filters.filter((name) => name !== filterName);
}

const selectedFilters = ['price', 'availability', 'size'];

removeFilter('price', selectedFilters);

Смотрите также delete.

delete

Полностью стирает что-то из сфер существования.

Представьте, что вы редактор контента, и есть пресловутый пост, от которого вы хотите избавиться. После того, как вы нажали блестящую кнопку «Удалить сообщение», CMS выполнила действие deletePost, а не removePost.

function deletePost(id) {
  return database.find({ id }).delete();
}

Смотрите также remove.

remove or delete? Если разница между remove и delete для вас не столь очевидна, я бы предложил взглянуть на их противоположные действия - add и create. Ключевое различие между add и create заключается в том, что add требует назначения, а create не требует места назначения. Вы добавляете элемент куда-то, но не "создаете его куда-то". Просто соедините remove с add и delete с create.

Подробно объяснено здесь (анг).

compose

Создает новые данные из существующих. В основном применимо к строкам, объектам или функциям.

function composePageUrl(pageName, pageId) {
  return pageName.toLowerCase() + '-' + pageId;
}

Смотрите также get.

handle

Обрабатывает действие. Часто используется при названии метода обратного вызова.

function handleLinkClick() {
  console.log('Clicked a link!');
}

link.addEventListener('click', handleLinkClick)

---

Context

Домен, в котором работает функция.

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

/* Чистая функция, работающая с примитивами */
function filter(list, predicate) {
  return list.filter(predicate);
}

/* Функция, работающая именно с постами */
function getRecentPosts(posts) {
  return filter(posts, (post) => post.date === Date.now());
}

Некоторые предположения, специфичные для языка, могут позволить опустить контекст. Например, в JavaScript обычно filter работает с массивом. Добавление явного filterArray было бы ненужным.

---

Prefixes

Префикс расширяет значение переменной. Он редко используется в именах функций (практически никогда).

is

Описывает характеристику или состояние текущего контекста (обычно логическое значение boolean).

const color = 'blue';
const isBlue = color === 'blue'; // характеристика
const isPresent = true; // состояние

if (isBlue && isPresent) {
  console.log('Blue is present!');
}

has

Описывает, обладает ли текущий контекст определенным значением или состоянием (обычно логическое значение boolean).

/* Bad */
const isProductsExist = productsCount > 0;
const areProductsPresent = productsCount > 0;

/* Good */
const hasProducts = productsCount > 0;

should

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

function shouldUpdateUrl(url, expectedUrl) {
  return url !== expectedUrl;
}

min/max

Представляет минимальное или максимальное значение. Используется при описании границ или пределов.

/**
 * Отображает случайное количество сообщений внутри
 * заданных границы мин/макс.
 */
function renderPosts(posts, minPosts, maxPosts) {
  return posts.slice(0, randomBetween(minPosts, maxPosts));
}

prev/next

Укажите предыдущее или следующее состояние переменной в текущем контексте. Используется при описании переходов состояний.

async function getPosts() {
  const prevPosts = this.state.posts;

  const latestPosts = await fetch('...');

  const nextPosts = concat(prevPosts, latestPosts);

  this.setState({ posts: nextPosts });
}

Единственное и множественное число

Как и префикс, имена переменных могут быть записаны в единственном или множественном числе в зависимости от того, содержат ли они одно или несколько значений.

/* Bad */
const friends = 'Bob';
const friend = ['Bob', 'Tony', 'Tanya'];

/* Good */
const friend = 'Bob';
const friends = ['Bob', 'Tony', 'Tanya'];

naming-cheatsheet's Issues

Clarification questions regarding naming

1. naming-cheatsheet/README.md

   Lines 95 to 97 in 4131482

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

   
   точно ли MenuItemProps будет хуже, чем Props, например, в этом случае?

   type Props = {}
   export class MenuItem extends Component<Props>{}

   type MenuItemProps = {}
   export class MenuItem extends Component<MenuItemProps>{}

2. naming-cheatsheet/README.md

   Lines 275 to 279 in 4131482

   	## Context
   	Домен, в котором работает функция.
   	Функция часто представляет собой действие над чем-то. Важно указать, какова его рабочая область или, по крайней мере, ожидаемый тип данных.

   
   тут согласен, но не противоречит ли это пункту "Избегайте дублирования контекста", указанному выше?

3. naming-cheatsheet/README.md

   Lines 297 to 299 in 4131482

   	## Prefixes
   	Префикс расширяет значение переменной. Он редко используется в именах функций (практически никогда).

   редко используется в именах функций (практически никогда)

   а как же имена функций-предикатов? 🤔