Чистый код. Роберт Мартин

Эту книгу я читал два года назад. Но единственное, что помню из неё, что мне не понравился перевод. Поэтому в этот раз я решил прочесть её в оригинале и заодно собрать годные мысли в заметках. Сегодня рассмотрим первые 4 главы.

Глава 1. Чистый код

В первой главе автор даёт определение чистому коду. Если собрать все описания в один список, то чистый код:

• элегантный и производительный;
• простой и недвусмысленный;
• читаемый и поддерживаемый;
• тестируемый и с минимально необходимым API.

Глава 2. Названия

Коротко:

• названия должны быть понятными и последовательными;
• в них не должно быть двусмысленности;
• аббревиатуры в названиях — плохо.

Используйте названия, объясняющие, что вы хотите сделать.

// плохо
let d; // elapsed time in days

// хорошо
let elapsedTimeInDays;

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

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

// плохо
let genymdhms;
class DtRec102 = { /* ... */ };

// хорошо
let generationTimestamp;
class Customer = { /* ... */ };

Переменная с хорошим названием быстро считывается и легко ищется. Использовать i, j, k стоит только для счётчиков. Названия функций и методов должны быть глаголами или начинаться с них. Геттеры, сеттеры и предикаты лучше называть с префиксами: get, set, is, has и так далее.

Используйте одно и то же слово для одного и того же понятия. Если в разных классах схожие методы называются по разному: fetch, get, load — то трудно запомнить, когда какой вызывать.

Глава 3. Функции

Коротко:

• короткие функции лучше громоздких;
• чем меньше аргументов, тем лучше;
• флаги лучше заменять на объект с настройками.

Функции не должны быть большими. Лучший размер для функции — 2–3 строки.

Каждая функция должна выполнять только одно действие. Но будьте аккуратнее с определением того, что такое «одно действие». Какие-то части можно вынести в отдельные функции, умейте останавливаться в правильный момент.

Названия должны полно описывать, что функции делают. Они должны быть консистентными, и недвусмысленными.

Больше, чем 3 аргумента использовать не стоит. Флаги лучше заменить на объект с настройками.

// плохо
const initPopup = (
  node,
  closeOnEsc=false,
  closeWithAnimation=false
) => {
  /* ... */
}

// хорошо
const initPopup = (node, options={}) => {
  const {
    closeOnEsc=false,
    closeWithAnimation=false
  } = options
  /* ... */
}

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

Глава 4. Комментарии

Коротко:

• комментарий не должен дублировать код;
• и должен сообщать дополнительные сведения, которых нет в коде.

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

// плохо
// if the employee is eligible for full benefits
if ((employee.flags.includes(HOURLY_FLAG)) && (employee.age > 65)) { /* ... */ }

// хорошо
if (employee.isEligibleForFullBenefits()) { /* ... */ }

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

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

В следующий раз

В главах 5–8 обсудим:

• форматирование, зачем оно нужно;
• структуры данных, абстракции;
• обработку ошибок и исключения.