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

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

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

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

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

Глава 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 и т. д.

Прим. автора поста: думаю, в конвертирующих функциях глагол можно опустить: convertIntToStr intToStr.

Используйте одно и то же слово для одного и того же понятия. Если в разных классах схожие методы называются по разному: 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 обсудим:

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