[N]ames

“The bad name of the method is akin to the election promises of politicians. It seems to be talking about something, but if you think about it, it’s not clear what it is.”

― C. MacConnell

---

[N01]: Choose Descriptive Names

Don’t be too quick to choose a name. Make sure the name is descriptive. Remember that meanings tend to drift as software evolves, so frequently reevaluate the appropriateness of the names you choose.

This is not just a “feel-good” recommendation. Names in software are 90 percent of what make software readable. You need to take the time to choose them wisely and keep them relevant. Names are too important to treat carelessly.

The power of carefully chosen names is that they overload the structure of the code with description. That overloading sets the readers’ expectations about what the other functions in the module do.

Example: C# | Java

[N01]: Используйте содержательные имена

---

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

Не рассматривайте это как дополнительный «фактор комфортности». Имена в программных продуктах на 90% определяют удобочитаемость кода. Не жалейте времени на то, чтобы выбрать их осмысленно, и поддерживайте их актуальность. Имена слишком важны, чтобы относиться к ним легкомысленно.

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

Пример: C# | Java

[N01]: Використовуйте змістовні імена

---

Не поспішайте із вибором імен. Подбайте про те, щоб імена були змістовними. Пам'ятайте, що сенс може змінюватися під час розвитку програмного продукту; частіше переосмислюйте доречність вибраних вами імен.

Не розглядайте це як додатковий фактор комфортності. Імена в програмних продуктах на 90% визначають зручність читання коду. Не шкодуйте часу на те, щоб вибрати їх осмислено, та підтримуйте їхню актуальність. Імена надто важливі, щоб ставитись до них легковажно.

Сила добре вибраних імен у тому, що вони доповнюють структуру коду описами. На підставі цих описів у читача формуються певні припущення щодо того, що роблять інші функції модуля.

Приклад: C# | Java

---

[N02]: Choose Names at the Appropriate Level of Abstraction

Don’t pick names that communicate implementation; choose names the reflect the level of abstraction of the class or function you are working in. This is hard to do. Again, people are just too good at mixing levels of abstractions. Each time you make a pass over your code, you will likely find some variable that is named at too low a level. You should take the opportunity to change those names when you find them. Making code readable requires a dedication to continuous improvement.

Example: C# | Java

[N02]: Выбирайте имена на подходящем уровне абстракции

---

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

Пример: C# | Java

[N02]: Вибирайте імена на відповідному рівні абстракції

---

Не використовуйте імена, які передають інформацію про реалізацію. Імена повинні відображати рівень абстракції, на якому працює клас чи функція. Зробити це непросто — і знову тому, що люди надто добре впораються зі змішуванням різних рівнів абстракції. При кожному перегляді коду вам з великою ймовірністю трапиться змінна, ім'я якої вибрано надто низькому рівні. Скористайтеся нагодою та змініть його. Щоб ваш код добре читався, ви повинні серйозно ставитись до його безперервного вдосконалення.

Приклад: C# | Java

---

[N03]: Use Standard Nomenclature Where Possible

Names are easier to understand if they are based on existing convention or usage. For example, if you are using the DECORATOR pattern, you should use the word Decorator in the names of the decorating classes. For example, AutoHangupModemDecorator might be the name of a class that decorates a Modem with the ability to automatically hang up at the end of a session.

Patterns are just one kind of standard. In Java, for example, functions that convert objects to string representations are often named toString. It is better to follow conventions like these than to invent your own.

Teams will often invent their own standard system of names for a particular project. Eric Evans refers to this as a ubiquitous language for the project. Your code should use the terms from this language extensively. In short, the more you can use names that are overloaded with special meanings that are relevant to your project, the easier it will be for readers to know what your code is talking about.

[N03]: По возможности используйте стандартную номенклатуру

---

Имена проще понять, если они основаны на существующих конвенциях или стандартных обозначениях. Например, при использовании паттерна ДЕКОРАТОР можно включить в имена декорирующих классов слово Decorator. Например, имя AutoHangupModemDecorator может быть присвоено классу, который дополняет класс Modem возможностью автоматического разрыва связи в конце сеанса.

Паттерны составляют лишь одну разновидность стандартов. Например, в языке Java функции, преобразующие объекты в строковые представления, часто называются toString. Лучше следовать подобным стандартным конвенциям, чем изобретать их заново.

Группы часто разрабатывают собственные стандартные системы имен для конкретного проекта. Эрик Эванс (Eric Evans) называет их всеобщим языком проекта. Широко используйте термины этого языка в своем коде. Чем больше вы используете имена, переопределенные специальным смыслом, относящимся к вашему конкретному проекту, тем проще читателю понять, о чем идет речь в вашем коде.

[N03]: По можливості використовуйте стандартну номенклатуру

---

Імена простіше зрозуміти, якщо вони ґрунтуються на існуючих конвенціях або стандартних позначеннях. Наприклад, при використанні патерна ДЕКОРАТОР можна включити в імена класів декоруючих слово Decorator. Наприклад, ім'я AutoHangupModemDecorator може бути надано класу, який доповнює клас Modem можливістю автоматичного розриву зв'язку в кінці сеансу.

Паттерни становлять лише один різновид стандартів. Наприклад, у мові Java функції, що перетворюють об'єкти на рядкові уявлення, часто називаються toString. Краще слідувати подібним стандартним конвенціям, ніж винаходити їх наново.

Групи часто розробляють власні стандартні системи для конкретного проекту. Ерік Еванс (Eric Evans) називає їх загальною мовою проекту. Широко використовуйте терміни цієї мови у коді. Чим більше ви використовуєте імена, перевизначені спеціальним змістом, що стосуються вашого конкретного проекту, тим простіше читачеві зрозуміти, про що йдеться у вашому коді.

---

[N04]: Unambiguous Names

Choose names that make the workings of a function or variable unambiguous.

Example C# | Java

[N04]: Недвусмысленные имена

---

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

Пример: C# | Java

[N04]: Недвозначні імена

---

Вибирайте імена, які максимально недвозначно передають призначення функції або змінної.

Приклад: C# | Java

---

[N05]: Use Long Names for Long Scopes

The length of a name should be related to the length of the scope. You can use very short variable names for tiny scopes, but for big scopes you should use longer names.

Variable names like i and j are just fine if their scope is five lines long.

Example: C# | Java

[N05]: Используйте длинные имена для длинных областей видимости

---

Длина имени должна соответствовать длине его области видимости. Переменным с крошечной областью видимости можно присваивать очень короткие имена, но у переменных с большей областью видимости имена должны быть длинными.

Если область видимости переменной составляет всего пять строк, то переменной можно присвоить имя i или j.

Пример: C# | Java

[N05]: Використовуйте довгі імена для довгих областей видимості

---

Довжина імені має відповідати довжині його області видимості. Змінним з крихітною областю видимості можна надавати дуже короткі імена, але у змінних з більшою областю видимості імена мають бути довгими.

Якщо область видимості змінної становить лише п'ять рядків, то змінній можна присвоїти ім'я i або j.

Приклад: C# | Java

---

[N06]: Avoid Encodings

Names should not be encoded with type or scope information. Prefixes such as m_ or f are useless in today’s environments. Also project and/or subsystem encodings such as vis_ (for visual imaging system) are distracting and redundant. Again, today’s environments provide all that information without having to mangle the names. Keep your names free of Hungarian pollution.

[N06]: Избегайте кодирования

---

Информация о типе или области видимости не должна кодироваться в именах. Префиксы вида m_ или f бессмысленны в современных средах. Кроме того, информация о проекте и/или подсистеме (например, префикс vis_ для подсистемы визуализации) также отвлекает читателя и является избыточной. Cовременные среды разработки позволяют получить всю необходимую информацию без уродования имен. Поддерживайте чистоту в своих именах, не загрязняйте их венгерской записью.

[N06]: Уникайте кодування

---

Інформація про тип або область видимості не повинна кодуватись в іменах. Префікси виду m_** або f безглузді в сучасних середовищах. Крім того, інформація про проект та/або підсистему (наприклад, префікс vis_ для підсистеми візуалізації) також відволікає читача та є надмірною. Сучасні середовища розробки дозволяють отримати всю необхідну інформацію без спотворень імен. Підтримуйте чистоту у своїх іменах, не забруднюйте їх угорським записом.

---

[N07]: Names Should Describe Side-Effects

Names should describe everything that a function, variable, or class is or does. Don’t hide side effects with a name. Don’t use a simple verb to describe a function that does more than just that simple action.

Example: C# | Java

[N07]: Имена должны описывать побочные эффекты

---

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

Пример: C# | Java

[N07]: Імена повинні описувати побічні ефекти

---

Імена повинні описувати все, що робить функція, змінна чи клас. Не приховуйте побічні ефекти за іменами. Не використовуйте прості дієслова для опис функції, яка робить щось крім цієї простої операції.

Приклад: C# | Java

---