Коммуникация – это процесс обмена информацией между людьми через общую систему символов, знаков или поведения. Написание кода легко подходит под это определение. Некоторые решения могут быть написаны одним человеком, но если продукт используется и расширяется, он в конечном итоге перерастет этого одного разработчика. Лучший пример — Facebook. Его написал Марк Цукерберг, но сейчас над ним работает гораздо больше разработчиков.

При этом, когда мы пишем код, мы пишем его не только для машин, но и для других разработчиков. Код должен быть максимально читабельным, потому что это канал общения между людьми. И что делает код читабельным? Что ж, если другой человек вас понимает, значит, вы добились успеха. Чем короче этот человек, чтобы понять, что вы пытались сказать, тем читабельнее ваш код. Поэтому мы должны стремиться к тому, чтобы это время было как можно короче.

Разбейте его на мелкие кусочки

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

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

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

Чтение длинного предложения — кошмар. Представьте, что вы читаете Уроки танцев для пожилых людей Богумила Грабала и пытаетесь понять его за один раз. Это 128-страничный роман, написанный одним предложением. Как насчет того, чтобы сделать это под давлением сроков?

То же самое касается кода. Длинные операторы, длинные методы, большие классы, несколько классов в одном файле… все это затрудняет чтение кода. Мы пишем набор инструкций, поэтому он должен быть максимально простым. Короткие методы легче понять другим программистам, и мы должны использовать их вместо длинных «умных».

Будьте максимально прямолинейны

«История» одного класса или метода должна быть максимально простой. Если вы хотите что-то сказать, вы должны говорить только это. И имя класса/метода должно быть достаточно описательным, чтобы указать его цель. Это может звучать глупо на бумаге, но на практике придерживаться этого гораздо сложнее.

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

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

Уважаемый клиент,

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

С уважением

И если кому-то нужны дополнительные пояснения, они всегда могут их попросить.

Какие приготовления?
Зачем вам нужен доступ к системе управления версиями? Кому это нужно?
Какая документация вам нужна?
Какой тип доступа к нашей среде вам нужен?

В коде это эквивалентно более глубокому копанию реализации. Если мы анализируем бизнес-логику, нам не нужно знать детали реализации для выборки данных. Это SQL, NoSQL или что-то еще? Это не важно для понимания того, что делает метод.

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

Делайте одно дело за раз

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

Какую тему мы должны поставить для письма, которое содержит обе темы? «Перевод проекта и собеседование»? Мы видим, что делаем два дела одновременно. Сначала это не кажется большой проблемой. Но представьте, когда клиент начинает отвечать на вашу почту, добавляя новых получателей. Кто-то начинает отвечать на первую часть, кто-то на вторую. Теперь вам нужно сослаться на это письмо, но только часть о собеседовании. Вы не можете этого сделать, вы включаете их во всю ветку. Вашим разработкам нужна часть, связанная с окружением. Опять же, вы включаете их в одну и ту же ветку. Все получают каждое письмо. Это быстро превращается в беспорядок.

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

Будьте описательными, называя вещи

Я уже затрагивал эту тему в предыдущем разделе. Когда мы отправляем электронное письмо, нам нужно установить тему. Представьте, что вы получили электронное письмо «Важно — прочтите». Или, может быть, "Это не работает". Какова цель этого письма? Нам нужно открыть электронную почту и прочитать, что внутри. Позже, когда нам нужно будет найти его среди кучи полученных нами электронных писем, как мы вообще узнаем, что искать?

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

Кроме того, когда мы называем вещи в нашем коде, мы должны следовать той же логике. Например, у нас есть свойство, которое определяет, может ли клиент включить какую-либо функцию. У меня есть тенденция называть логические значения как вопросы (IsDeleted, IsPublished, HasFeatureEnabled…). Таким образом, когда я пишу код, он будет выглядеть примерно так:

if(customer.HasFeatureEnabled) {
// делаем что-то
}

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

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

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

Будьте последовательны, называя вещи

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

Теперь наш клиент — это компания, у которой есть другие компании для клиентов, у которых есть люди в качестве клиентов. В этом предложении слово «клиент» используется для описания трех разных вещей, а слово «компания» используется для описания двух разных вещей. В двух случаях клиент и компания — одно и то же.

Если мы пишем электронное письмо и говорим о клиенте, кого мы имеем в виду? И если мы однажды говорим «клиент», а в другой раз «компания времени», мы просто усложняем жизнь тому, кто читает нашу электронную почту. Мы должны договориться, как назвать что-то и придерживаться этого.

Если что-то называется Tenant, оно должно называться Tenant во всех электронных письмах. Если мы иногда называем это Аккаунт, Клиент или Компания, хотя это правильно, мы не согласны с этим, и это может вызвать путаницу. .

Избегайте сленга

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

Многие люди пишут код таким образом, и это в конечном итоге приводит к двум вещам: 1) вам либо нужно делать все самому, либо 2) вам нужно будет объяснять свой код другим разработчикам каждый раз, когда кто-то другой вносит в него изменения.

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

Допустим, нам нужно что-то сделать по конкретным инструкциям. Эти инструкции были отправлены нам по электронной почте. Находим ветку электронной почты и начинаем ее просматривать. Мы не читаем каждое письмо в нем, мы только просматриваем его, чтобы найти то, что нам нужно. Представьте теперь, что мой друг прислал нам эти инструкции, используя выдуманные сокращения и акронимы. Теперь снова представьте, что вы читаете это под давлением сроков.

Я нашел много подобных вещей в коде, над которым работал. Пространство имен под названием GTK, которое не имеет ничего общего с пользовательским интерфейсом, AccService, который не имеет ничего общего с учетными записями, имена длиной более 8 букв, которые не образуют никакого осмысленного слова и выглядят как случайно сгенерированная строка… Некоторые из них были моими, некоторые — другими программистами. код. Но в итоге во всех этих случаях работать над кодом было тяжелее, чем должно быть.

Разбить его рано

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

Несколько раз я получал письма примерно такого содержания:

Сообщаем вам о [некоторых действиях]. Если вы уже выполнили [это действие] или оно не относится к вашему делу, проигнорируйте это письмо.
[содержимое письма]

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

Заключение

Писать код легко. Читать позже, не так уж и много. В тот момент, когда мы писали код, у нас были все факты в голове, и мы были полностью отданы задаче. Но со временем это знание угасает, и мы оказываемся в ситуации, когда нам нужно его переучить. Если кому-то другому нужно выполнить задачу на нашем старом коде, и он не читаем, есть большая вероятность, что эта задача в конечном итоге вернется к нам. Это приведет к пустой трате времени двух разработчиков, а не к ускорению процесса. Время — дорогой ресурс, и мы должны инвестировать часть его сейчас, чтобы потом сэкономить.