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

Именование относится к присвоению имен коду или абстракциям данных, например:

  • Имена переменных.
  • Имена функций.
  • Имена классов.
  • Таблицы данных, коллекции или имена отношений.
  • Любая другая абстракция, на которую будут ссылаться в другой части программы (например: свойства, перечисление, ключи,…)

Именование вещей как программиста на самом деле идет дальше, чем сам код:

  • Пакеты, Файлы, Имя проекта, Имена репозитория.
  • Экземпляры серверов, имена образов.
  • Конечные точки API, имена заданий Jenkins и т. Д.

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

Почему так важно называть вещи?

  • Понятный код. Имена уменьшают потребность в обширных комментариях и документации.
  • Планирование. Имена дают представление о том, как работает система в целом, и о будущих намерениях разработчика.
  • Улучшенный дизайн программного обеспечения. Правильное наименование вещей помогает достичь лучшего дизайна программного обеспечения, проясняя состояние ума.
  • Повышайте продуктивность команды.

«Написание кода намного проще, чем его чтение».

Этот факт остается верным, если вы работаете в команде или через несколько недель возвращаетесь к своей кодовой базе, даже не глядя на нее.

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

Хорошая новость в том, что вам нужно лишь немного воли, чтобы улучшить свои «навыки именования».

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

Как правильно называть вещи

Правильное наименование вещей зависит от контекста (например, система, язык, команда, проект, предметная область и т. Д.). Ниже приведены некоторые общие рекомендации и примеры.

Имена в целом

  1. Должен быть значимым в их контексте.
  2. Кратко-описательные, а не длинные-описательные имена.
  3. Должен раскрыть намерение.
  4. Именование должно быть последовательным (например: создать соглашение об именовании для команды).

Значимые в их контексте

  • Имена помогают понять логику. Они должны быть различимы.
total = price * quantity
total2 = total * tax_rate
total3 = account_credit + coupon_value
if (total3 < total2) { // Completely unclear what we are comparing 
  processOrder()
}
// Bad naming
  • Любая переменная, которая использует числовое значение, чтобы отличать ее от аналогичной переменной
    , требует рефакторинга.
payable_total = price * quantity * tax_rate
available_funds = account_funds + coupon_value
if (available_amount < payable_total) {  
// Clear, and we've even spotted a mistake in this comparison.
  processOrder()
}
// Better naming
  • Найдите точное имя. Иногда это требует изучения словарного запаса, но, на мой взгляд, это вложение стоит того.
var total2                 // Very bad, don't do this.
var amount_total           // Mmmh.
var order_total_with_tax   // Eh, a bit too long.
var payable_total          // Yes, finally clear!
  • Избегайте слов, которые не имеют никакой ценности.
let data = await readGoogleReverseGeocodeApi(location) 
// Bad. We know there is "data" in a variable! "data" is probably one of the worse variable name possible anywhere.
let addressObj = await GoogleAPI.getReverseGeocode(location)
// Better

Выявление намерений

  • Сделайте очевидным намерение переменной или функции (если таковая имеется).

Пример для логической переменной:

var empty = true
// Bad
var isEmpty = true
// Ok, it is now obvious that the variable is a boolean.

Пример функции:

function isEnabled() { return boolean }
// Good, it is obvious that the function purpose is to return a boolean.
class User { 
...
updateUserInfo (name) {
 this.name = name
} 
// Bad, unnecessary long function name and vague.
setName (name) {
 this.name = name
} 
// Ok, short and descriptive.
// user.setName(name) versus user.updateUserInfo(name)

По возможности используйте простые слова

  • Простые слова обычно легче запоминать и понимать (в отличие, например, от сокращений). Если возникает конфликт имен, обычно это происходит из-за недостаточной модульности кода.
<RITE type='text' defaultValue='20' /> 
// What is the RITE acronym stands for? (React-Inline-Text-Editor)
<Editor type='text' defaultValue='20' />
// OK, pretty self-explanatory.

Я могу быть предвзятым, поскольку в целом я очень не люблю аббревиатуры. Когда есть выбор, я предпочитаю простое произносимое слово вместо сложного.

Последовательно используйте стили кейсов

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

Типы стилей особого случая:

  • camelCase, CamelCase (например, iPhone, FedEx)
  • snake_case (например, car_speed)
  • kebab-case (например: игровой уровень)

В Javascript, например:

// Constants are usually in SNAKE_CASE.
const COOKIE_MAX_AGE = 30
const ITEM_PER_PAGE = 4
// Variables are usually in camelCase.
let jsonFile
// Class are usually CamelCase.
class Layout {  ... }

То, как использовать подчеркивание, верблюжий регистр или что-то еще, часто является личным или командным выбором. Важная часть - быть последовательным.

aRatherLongName
a_rather_long_name
// Which one is easier to read?

Короткие или длинные имена?

По-разному.

  • Переменные с коротким временем жизни или короткой областью видимости должны быть кратко названы (например: счетчик цикла может быть одной буквой. Локальные переменные могут быть отдельными словами. Глобальные переменные обычно должны быть более сложными).
for (let r of rows) { ... }  
// OK. One letter variable "r" is fine the loop here.
function getCoordinates (lat, long) { }  
// OK. "lat" in this function context refers clearly enough to "latitude".
  • Однако удаление нескольких букв из слова только для сокращения имени, как правило, не является хорошей идеей.
UpdatePriceCr.start()
// Bad, removing 2 letters of the word Cron (Cr) unnecessarily makes it less descriptive.
var ag = new Agenda()
ag.sch(time)
// Bad,  removing 4 letters of the word schedule (sch) unnecessarily makes it less descriptive.
  • Какой лучше?
// naming A
let dR
let dCV
let dK
let dDin
// naming B 
let radius
let curvature
let conic_constant
let inner_aperture

Это непростой вопрос.

Эти переменные, кажется, используются в контексте оптической физики, где будут вычисляться математические формулы. Кто-то, знакомый с оптикой, может сразу понять, что означает dR или dCV, особенно если это обычные сокращения в книгах по физике. Это особая ситуация, когда короткие сокращения подходят или даже лучше, поскольку они позволяют прямое сравнение с формулами учебника.

Все еще не знаете, как называть вещи?

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

«Через 2 года я прочитаю эти строки и быстро пойму, что происходит, или это будут археологические раскопки?»

Если ответ отрицательный, потратьте минуту или две, пытаясь придумать лучшее название. Не сдавайся.

  • Как я могу помочь кому-то другому быстро понять мой код?
  • Есть ли слово, которое имеет лучшее значение / более простое / более точное?
  • Имена выглядят одинаково? Могу ли я переименовать несколько вещей, чтобы не было путаницы?

Эта привычка думать может улучшить качество вашего кода и ваши навыки абстракции.

Ссылки и дополнительная информация.