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

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

ТОДОС

Используйте имена, которые хорошо выражают намерения

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

  • С какой целью он используется?
  • Что оно делает?
  • Как это можно использовать?

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

Предположим, вы хотите назвать переменную для расстояния, измеряемого в метрах. Не называйте его distance, meters или m и так далее. Гораздо лучше будет distanceInMeters. Это даст вам четкий контекст и намерения, которые должна выражать эта переменная. Отсутствие этих ценностей является большой проблемой.

Создавайте имена, которые четко различаются

Никогда не рекомендуется использовать одинаковые или похожие имена для разных целей. Мы не в состоянии увидеть четкую разницу между тем, что скрывается под этими именами. Возьмем для примера имена методов. Является ли хорошей идеей назвать два метода getProduct(UUID id) и getProductInfo(UUID id)? Нет, потому что мы не знаем, в чем заключается эта небольшая разница. Мы вынуждены проверять, что они возвращают и какой код выполняется внутри них. Конечно, в этом примере нас утешает то, что они действительно что-то возвращают. В противном случае было бы еще труднее заметить разницу.

Другим примером является использование чисел для нумерации переменных с одинаковыми именами, например. product1, product2 и так далее. Хотя такие названия не вводят в заблуждение, но тем не менее неинформативны.

Придумайте имена, которые вы можете произнести

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

Используйте имена, по которым легко искать

На практике каждая в настоящее время IDE предлагает функцию поиска по всему проекту. Вы можете искать классы, методы, переменные и т. д., вводя строки в строку поиска. Следовательно, это еще один аргумент в пользу того, чтобы не использовать отдельные буквы в именах. Предположим, вы вызвали переменную с буквой e. Из-за того, что это наиболее часто используемая буква в английском языке, список результатов будет огромным, когда дело доходит до поиска переменной e. Называя переменные таким образом, разработчик намного усложняет себе жизнь.

Рекомендуется объявлять статические переменные в начале классов. Допустим, мы делаем статическую переменную с именем MIN_LETTERS_PER_DAY равной 3. Благодаря этому будет легче найти эту переменную с функцией поиска. Но есть еще одна причина для этой практики - если окажется, что это значение должно быть равно 4, то все, что вам нужно сделать, это изменить 3 на 4 в одном месте, а не в каждом месте, где это значение было использовано.

Используйте глаголы в именах методов

Имя метода должно быть глаголом или отглагольным существительным, например activateAccount или accountActivation, точка. Более того, методы, которые являются аксессорами, мутаторами или предикатами, должны быть созданы на основе управляемого значения, такого как getExpirationTimestamp, setName и isActive.

Используйте одно слово для концепции

Разработчики должны придерживаться одного и последовательного словаря для проекта. Использование разных имен для аналоговых методов в разных классах не является оптимальным решением. Например, вы не должны использовать get, fetch и retrieve взаимозаменяемо. Значения этих имен немного отличаются, поэтому у других разработчиков может возникнуть сомнение в том, что эти методы выполняют одни и те же операции. Итак, как вы можете видеть, соблюдение этого правила очень важно для качества нашего кода, потому что то, насколько ваш код понятен другим, является огромным фактором конечного качества.

Используйте имена областей решения и проблемы

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

Добавьте важный контекст

Обычно нет возможности назвать элемент каким-либо рациональным способом с точки зрения придания ему достаточного контекста. Но на помощь приходит правильное наименование этих компонентов, в которых находится наш элемент (например, классы или методы). Называть их так, чтобы они тоже могли принести какую-то нужную информацию и как-то освободить от части ответственности за предоставление достаточного контекста. >. Допустим, у вас есть класс Foo, и он отвечает за что-то совершенно отличное от метода, который вы хотите создать в этом классе. Этот метод будет, например. совершение реального телефонного звонка с использованием сторонней библиотеки, и он будет называться makePhoneCall(String from, String to). Несмотря на то, что в классе Foo не должно быть реализованных методов, которые с ним вообще не связаны, есть возможность переименовать его в make(String from, String to) благодаря перемещению во вновь созданный класс с именем PhoneCall. Тогда класс Foo мог бы просто вызвать что-то вроде этого: PhoneCall.make(“+48123456789”, “+48987654321”) если бы этот метод был статическим, конечно. Кстати, у этого есть еще одно преимущество — когда у вас есть класс PhoneCall, вы можете разделить тело нашего метода на несколько методов, чтобы сделать вещи более ясными и понятными.

НЕ ТОДОС

Избегайте дезинформации

В одном из предыдущих советов я писал о присвоении имен, которые представляют хороший контекст. В этом я хочу предупредить об именах, которые дают плохой или неясный контекст. На мой взгляд, это даже хуже, чем вообще не указывать контекст. Такое поведение дезинформирует всех, кто работает с нашим кодом, и даже нас самих. Простой пример: допустим, у вас есть карта, представляющая собой набор некоторых продуктов. Присвоение этой коллекции имени productsList означает, что это не карта, а список. Это был всего лишь простой пример, но ситуация может стать более серьезной, если вы замените имя insert для метода на save.

Не используйте префиксы

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

Избегайте ментальных образов

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

Не используйте глаголы в именах классов

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

Не будь смешным

Имена должны хорошо показывать свое значение. Если вы шутите, то затемняете его и он недостаточно прозрачен. Дело в том, что когда вы шутите, вы используете какие-то разговорные обороты или сленг, который не всегда всем понятен (в основном только вам или узкой группе людей).

Не делайте каламбуров

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

Не добавляйте слишком много контекста

В этом посте я уже писал о необходимости добавления контекста, правильно давая имена классам и методам. Из-за этого вы не должны переусердствовать, добавляя слишком много контекста для элементов, которые являются их частью. Это становится ненужным, потому что мы уже знаем это из остального кода. Например, если у нас есть простой класс DTO UserDto, нам не нужно использовать слово user в имени каждой переменной в этом классе. Ни у кого не возникнет сомнений, что переменная id является идентификатором пользователя, потому что она уже вытекает из контекста, заданного именем класса UserDto.

Резюме

Лично я не раз сталкивался с некоторыми случаями нарушения вышеуказанных правил. Что интересно, в основном это было, когда я работал над проектами для Android. Я думаю, что причина в том, что мобильные проекты обычно намного меньше, чем бэкенд. Часто над мобильным приложением работает один человек, поэтому он считает, что ему не нужно уделять столько внимания чистоте кода. К сожалению, проект Android от начала и до конца разрабатывается одной компанией редко, и поэтому другому разработчику приходится сталкиваться с чужим кодом. Я был этим другим разработчиком не раз. Затем я увидел несколько смешанных названий для одних и тех же элементов кода, несколько шуток, а также много дезинформативного контекста. Эти проблемы часто трудно исправить, потому что они требуют много времени, чтобы сначала понять их, и только после этого вы можете приступить к рефакторингу.

Как и в первом посте, я напоминаю вам, что содержание этого также основано на книге Роберта С. Мартина Clean Code: A Handbook of Agile Software Craftsmanship. Я надеюсь, что в этом посте я дал вам широкий и полезный совет по именованию в программировании. Лучше всего придерживаться их всех, но я думаю, что самое главное — помнить, что код, который мы пишем, предназначен не только для нас, но и для других. И на этом крутом выводе мы можем закончить этот пост, но перед этим я хотел бы выразить свой интерес к вашему мнению. Итак, есть ли другие хорошие или плохие привычки, с которыми вы сталкивались или применяли? Я призываю вас подумать об этом и поделиться своими мыслями, оставив комментарий.