Как стать автором
Обновить

Делай нейминг как сеньор

Время на прочтение 13 мин
Количество просмотров 114K
Всего голосов 186: ↑184 и ↓2 +182
Комментарии 221

Комментарии 221

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

А вообще за четверть века в профессиональной разработке я понял, что глобально у кода есть только одна характеристика: человек думал о том, что он кодит, или не думал, а еще точнее - человеку нравится его работа или лишь бы поскорее этот клятый тимлид наконец от меня отстал (в частности с вопросом почему у тебя сущность называется Pizza, хотя на самом деле это Cappuccino - ведь компилятору вообще без разницы)

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

Ещё круглые кнопки на Delphi.

Это какой-то мем?

На любом форуме по Дельфям в начале нулевых было много вопросов на тему "как сделать кнопку круглой/овальной/любой формы".

И хренова куча сторонних компонентов на эту тему)

В разрезе «ремесленник/мастер» оказались интересны "Раздумья ездового пса" В.В. Ершова… можно по ключевым словам «мальчик на тойоте» глянуть именно те места.

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

Дополню:
В программировании две проблемы — именование переменных, инвалидация кэша и ошибка на единицу)

а как же разыменование нулевого указателя (оно же NullReferenceException), деление на ноль и самое страшное - утечки памяти?
(впрочем, я слишком молода и, возможно, не распознала мем)

впрочем, я слишком молода и, возможно, не распознала мем

Таки-да, мемом является фраза про инвалидацию кеша и именование пременных, а уж на её основе родилась куча вариаций: https://martinfowler.com/bliki/TwoHardThings.html

Naming (things) это еще и перечисление. Две сложные вещи: инвалидация кеша и перечисление вещей.
Отчего шутка становится более программистской.

Done)

TL;DR Cиняя книга права, единый язык нужОн.

Вы, конечно же, имеете в виду книгу Эрик Эванс. Предметно-ориентированное проектирование (DDD). Структуризация сложных программных систем?

А какие ещё варианты?

Мало ли синих книг про единый язык, начиная с букваря.

Есть еще более "синяя", точнее, сине-зеленая книга "Предметно-ориентированное проектирование, самое основное", Вон Вернон.

Книжка Вернона красная.

Синева в глазах смотрящего. (Ну, или краснота.)

А как же Зелёная книга?

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

Писать на русском не привычно, но код внезапно был бы более понятный чем couriersShiftsDuration, ordersPerCourierLabourHour, Health permit, Nutrition facts

Было бы логично, если продукт никогда не будет выходить в другие страны. У нас сейчас 17 стран и в этих странах разработчики (которые пользуются API например) — они совсем не знают русский.

Так пусть учат. Чем мы хуже?

Извините, но это ложная альтернатива: «не учат язык = считают нас хуже».
До 20 века международным языком был французский, сейчас английский. Нашим разработчикам приходилось читать инструкции по немецки, когда нужно было интегрироваться с немецкими системами оплаты. Было больно, без претензий к немецкому. Просто даже второй язык выучить не то, чтобы просто.

Так вы главные - пусть учат. И тут не язык - тут набор терминов. Это же не инструкция а имена переменных. Спутник выучили и остальное выучат. Главное начать.

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

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

Если вам верить, санскрит вообще на первом, но его почему-то мало кто учит. Задумайтесь, почему.

Потому что это МЁРТВЫЙ язык!

Именно. Мёртвый - то есть им не пользуются. И русским в окружении иностранца тоже не пользуются. Так какая для него конкретно разница между санскритом и русским?

Ну и русскому недолго осталось

И какое до этого дело, скажем, жителю США?

Ещё, кстати русский - один из 5-ти официальных языков ООН.

Кто ещё среди них? арабский и китайский? -- точно, давайте называть переменные по-арабски да по-китайски, чтобы всем европейским программистам было в равной степени больно.

Внезапно, английский — тоже.

Судя по тенденции на геополитической арене, следующим lingua franca будет арабский или китайский. Что тогда станут делать программисты?
И я бы заглянул ещё на полшага вперёд: в связи с тем, что Госдума приняла закон о запрете применения иностранных слов, за исключением случаев, когда нет эквивалента, что будет, если особо ретивые чиновники/руководятлы начнут применять нормы закона и к коду на ЯП? ))

P.S. Минусаторы, расслабьтесь, это всего-лишь размышления.

У китайского языка очень сильное ограничение — нет алфавита.

Всё лучше, чем английский с его шестью вариантами произношения "ough" и прочим весельем. В китайском эта неоднозначность прочтения хотя бы явно выражена, как мы, программисты, и любим.
/s

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

Писать переменные на русском или в транлитерации - неуважение прежде всего к себе, коллегам (даже если они все русскоговорящие) и к IT сфере в общем

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

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


Задачи ставит бизнес на русском вот и выходит бессмысленный перевод туда-сюда, перевод ради перевода

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

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

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

>смена язык для именования переменных излишняя трата времени
А набирать переменную в пол строки -- не трата времени? А изучать значение каждого слова в нескольких источниках? А составлять словари переменных?

А набирать переменную в пол строки -- не трата времени?

3-5 первых символов, CTRL+SPACE, TAB. Трата времени только при работе в блокноте. И это намного лучше, чем лезешь в код, а там всякие TextBoxN и весь алфавит, в котором хранятся магические данные. Причем сам разработчик уже через неделю не может понять как оно работает.

А изучать значение каждого слова в нескольких источниках?

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

А составлять словари переменных?

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

3-5 первых символов, CTRL+SPACE, TAB

В статье приводятся примеры "правильных" названий перменных:

tripsWithOneOrderCount
tripsWithTwoOrdersCount
tripsWithThreeOrdersCount
tripsWithFourOrdersCount
tripsWithFiveOrMoreOrdersCount

Я тут насчитал 10-11 символов до "CTRL+SPACE, TAB". И это далеко не самые страшные случаи при таком подходе

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

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

У нас и так много обвеса

Видимо, это потому что процесс важнее результата

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

Я тут насчитал 10-11 символов

Или пара нажатий стрелок.

Примерно как знание, что Пномпень это столица Камбоджи

Если вы работаете там, где важно знание, что Пномпень - это столица Комбоджи, то да - это важное знание.

Видимо, это потому что процесс важнее результата

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

Я тут насчитал 10-11 символов до «CTRL+SPACE, TAB». И это далеко не самые страшные случаи при таком подходе
Там, на самом деле, обычно, не нужно именно первые писать. Можно вводить что-нибудь типа «trwt», чтобы подсказка выдала ранее объявленную «tripsWithTwoOrdersCount».

Ну так запишите ИНН как INN вместо какого-нибудь Tax Number (может быть много вариаций)
Но только проблема будет в том, что само по себе абстрактный INN тоже ни черта не понятная вещь, и придется добавлять комментарии.

В случае со складом - создайте класс Warehouse, и в будущем все программисты будут его использовать, никому не придет в голову создавать еще один класс для склада с названием Store. Я вообще не понимаю в чем проблема «можно перевести разными способами», если достаточно создать имя классу всего однажды, и все будут его использовать, и IDE поможет, и документацию (внезапно) можно подключить к кодовой базе.

Не оправдывайте банальную лень придуманными проблемами. В 2024 году не знаешь английский = ты мертвый специалист.

В DDD есть принцип Единный Язык (Ubiquitous Language)

Эксперты предметной области (Domain Experts) и разработчики программного обеспечения работают вместе, чтобы создать общий язык для разрабатываемых бизнесс-сфер. Тут не может быть противопоставления, это единная команда. Разработка программного обеспечения это инвестиция в бизнес, а не просто статья расходов. Усилия, прилогаемые к созданию Единого Языка (Ubiquitous Language), помогают распространить глубокое понимание Домена (Domain) среди всех членов команды.

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

  • Единный Язык (Ubiquitous Language): Эксперты предметной области (Domain Experts) и разработчики программного обеспечения работают вместе, чтобы создать общий язык для разрабатываемых бизнесс-сфер. Тут не может быть противопоставления, это единная команда. Разработка программного обеспечения это инвестиция в бизнес, а не просто статья расходов. Усилия, прилогаемые к созданию Единого Языка (Ubiquitous Language), помогают распространить глубокое понимание Домена (Domain) среди всех членов команды.

Полностью согласен. Программист должен говорить на языке заказчика. Иначе время разработки растёт многократно.

Конечно, можно на лету переводить термины туда-сюда, но это пустая трата сил.

Справедливости ради, видел проект, где в процессе разработки разъехались переводы терминов у фронтенда и бэкенда, так что "никому не придет в голову создавать еще один класс" - слабый аргумент.

А ещё англ слова короче. В среднем на одну букву. В тысячах строк кода - это тысячи букв.

И сколько букв в английском эквиваленте слова "защищающийся"?)

Ещё и транслитом - бррр

Да тут даже не совсем в этом проблема....

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

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

Defender - 8

Defender

но это защитник

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

Context.reverso по запросу "защищающийся" как раз и выдал "defender". Равно, как и "defending". Зависит от контекста, конечно, но имеет место быть

Defending? 9 против 12

Это - защищающий

Верно, правильнее тогда self-defending

Это вообще не существительное, а причастие

Равно как и "защищающийся"

дефенсибля)

Defendant?

Это "ответчик"

Нейминг - это не просто перевод. А деепричастиям и причастиям нечего делать в коде.

А деепричастиям и причастиям нечего делать в коде.

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

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

Назовите, пожалуйста, пример такого термина, что не попадает в категорию базового английского.

Если вы опираетесь на 1С в своих аргументах, то это скорее антипример из ада. Этот софт должен умереть, а программисты 1С/на 1С - пройти курс психотерапии и реабилитации

СНИСЛ?

SSI

P.S. Он СНИЛС :)

СНИЛС -- это SSN, а SSI -- это Server Side Includes :)

Или social security income ;o)

Но да, ssn.

Экстракорпоральное оплодотворение (ЭКО), штрихкод, Контрольно-кассовая машина (ККМ)

Про ЭКО не скажу, но остальное barcode и till

Till -- это что-то из прошлого века :)

Сейчас это POS (point of sale)

in vitro fertilization

В статье есть такой пример - зарплата. Переведёте это как salary и будет ошибка.

Честно говоря, не совсем понимаю, что с salary не так

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

По поводу таксиста соглашусь (правда при условии, что он работает не на некую компанию).

Согласно Collins English Dictionary:

A salary is the money that someone is paid each month by their employer, especially when they are in a profession such as teaching, law, or medicine.

Сумма денег выплачиваемая работнику работодателем ежемесячно, особенно, если сфера деятельности обучение, право или медицина.

В то время как incentives согласно тому же словарю:

1. motivating influencestimulus (мотивация, стимул)

2. a. an additional payment made to employees as a means of increasing production (дополнительная оплата работнику, призванная увеличить производительность - т.е. есть фактически премия)

Я так понимаю, что именно вот этот момент и намекает на исключительно умственный труд - "особенно если сфера деятельности обучение, право или медицина"?

А вообще, все это только лишь подтверждает идею о том, что правильный нейминг выбрать довольно сложно)

Всё верно. Мы выбрали максимально общее incentives, потому что это агрегат, внутри которого есть wages, premiums и прочее.
Пока отправляем весь нейминг на ревью нашим международным бизнес-девелоперам, которые шарят что там как именуется правильно (уточню, что пока это касается внешних API и новых проектов). Очень важен контекст, просто сторонний переводчик может не так перевести. И вот имея накопленный словарь уже можем смелее сами орудовать терминами. Так что да, это сложно и научить каждого разработчика так переводить не получится. Нужно находить возможность построить такой процесс внутри организации.

Спасибо Вам большое за статью и за разъяснения)

Я как бы согласен с идеей статьи, но вот тут на мой взгляд перебор. Неправильно считать, что все англоговорящие коллеги вот прям совершенно верно понимают словарную разницу между incentives и salary. А ещё будут сотрудники из других стран, для которых английский тоже не родной. Я 10 лет в англоязычной среде живу и много видел:) Если термин не совершенно в доску очевидный, то лучше не полениться и уже писать base monthly salary, variable premium и там total fixed and variable monthly pay - ну например, я не сильно долго думал. Куча людей не прочитав словаря скажут, что incentives, bonuses and premiums - это синонимы. Даже если Вы формально правы.

Внутри incentives ещё и не-денежная мотивация должна быть. И условно денежная, но не выплачиваемая работнику: медицинская и прочая страховка, обещанное повышение по должности и так далее.

А они точно шарят? Максимально близкий к русской "премии" термин в контексте оплаты за труд это "bonus". "Premium" это премиальный, или, по-русски, первосортный, например "premium ingredients".

Для термина "incentives", как Вы его поясняете в комментарии выше, существует давно устоявшееся C&B - compensation and benefits. И т.д.

Плюньте. Составьте словарик транслита для зарубежных разработчиков - они привыкнут, а вашим будет проще и понятней. Как писал выше медицинских книжек в западном общепите (по крайней мере в той части где приходилось работать) не существует как понятия. Трудовых книжек не существует как понятия. Многих справок не существует как понятия. В части бюрократически-государственных терминов с русским языком сравнится только немецкий. Английский здесь бедноват.

"Premium" это премиальный, или, по-русски, первосортный, например "premium ingredients".

Да, но не только: https://en.wiktionary.org/wiki/premium#Noun

НЛО прилетело и опубликовало эту надпись здесь

Не исключено, что вы шарите лучше. Тем не менее premiums был совершенно сознательно выбран.
В плане транслита — плохо масштабируется. Прочувствовать подобный опыт можно, если читать на турецком, например. Такие слова даже запомнить тяжело, что уже говорить о том, чтобы не опечататься или использовать их в коммуникации. Хотя вроде латиница.

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

У турок, видать, комплекс неполноценности недостаточно развит, не то, что у эксСССР...

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

Первое событие в бух учёте. ;)

Хотя я выше и написал кому то что переменные надо на английский переводить для того чтобы код читаемый был. Но когда такие комментарии как ваш вижу... Так и хочется спросить кто вы такой в плане экспертизы? Что отправляете флагманскую и вполне рабочую бухгалтерию в ад и не считаетесь с очевидным - есть 100500 продуктов и сайтов и API, в российском сегменте, где есть ИНН. В 99% поле будет называться inn, а не tin, потому что это самое читаемое для всех и понятное. Также и "физлицо" многие обозначат как FL, и не будут морочаться с Person, Human или Individial. Кроме вашего мира радикального есть ещё и практика реальная, в которой много конвенций.

А еще есть sap, где проскакивают немецкие корни, например дебит/кредит это внезапно H(aben)/S(oll)

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

а не мучаться со словарями для терминов

Скорее всего сильное влияние оказывает то, что 90% информации ищется на английском. И тут уже личное мнение, что название переменных вроде PoleznayaNagruzkaZaprosa режет глаз, многие языки конечно поддерживают utf-8 но мешать два языка как-то не очень(опять же мое мнение), ну и в целом в большинстве проектов нейминг +/- предсказуемый и большинство пониамет о чём идёи речь.

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

$handler->sendToQueue($platezhka)

1) в русском и так часто есть вкрапления английских слов, например e-mail, Mysql, XML, HTTP, KFC, McDonalds и др слова, бренды и аббривиатуры

2) я против транскрипции, мы же не поляки

3) ваш пример выглядел бы так: обработчик->вОчередь(платежка) или вроде того

UPD для добавления внешних библиотек в целом стоит использовать свои интерфейсы см паттерн мост (Bridge)

Ну да, вопрос стратегии. Лично я вижу только три варианта:
— придерживаться локальных названий в своей логике, и забить на мешанину;
— придерживаться локальных названий в своей логике, и писать обёртки для библиотек (что само по себе МОЖЕТ иметь смысл, не только из-за языка);
— перейти на английские наименования, чтобы избежать смешения языков.

Лично я придерживаюсь последней стратегии, потому что писать фасады/мосты для подключаемого кода в 80% случаев будет напрасным трудом (в моей работе), а смешивать понятия из разных языков не люблю, перфекционизм мешает.
BTW проблема не конкретно в русском языке и кириллице. Для польского программиста код вроде
$zasob->dodajDoKolejki($zamowienie)

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

Примерно два года назад работал в чисто польской фирме (был единственным иностранцем), и мы пилили проект на польский и чешский рынок. Тикеты в джире на польском, конфлюенс на польском, общение в команде тоже. А код — на английском. Потому что мировой стандарт.

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

Если бы да кабы‚ да во рту росли б грибы, тогда был бы не рот, а целый огород.

все рекомендации к разработке в первую очередь предназначены для них, а весь мир подстраивается

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

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

в нашу сферу влияния могли бы войти славянские страны и те кто кириллицу использует

Вы чешский или белорусский свободно понимаете? Кирилица != русский язык.

Это ещё что! Вот у меня в одном проекте есть такой смешной фрагмент:

Quer = New Query;
Quer.Text = Catalogs.ОтчётыWebСервиса.FindByDescription(NameReport,True).ЗапросКБазе;

Это после "рефакторинга" обработки web-сервиса 1С на англоязычный синтаксис осталось...

А зачем его вообще делали?

Перевод терминов на уровне носителей языка могут делать только носители языка. Даже хороший программист не всегда знает английский до таких тонкостей (да и не должен). И тратить его время на изучение особенностей названий того же заработка — не очень разумно.
Иногда такие переводы и вовсе могут ввести в заблуждение и привести к ошибкам, хотя вроде как всё это делалось для их избежания.
Так что по этой части нужен явно не тот подход, что указан в статье. Хотя в остальном мысли здравые

Вы совершенно правы.
Проблема не в незнании английского - проблема в недостаточном знании предметной терминологии как на английском, так, зачастую, и на русском. Пример прямо из текста статьи: Health Permit как аналог медицинской книжки. Ближайший русский аналог термина Health Permit - это "Разрешение на соответствие санитарным нормам", выдаваемое Роспотребнадзором предприятию (раньше сертификат СЭС), а не сотруднику. А вот ближайший аналог российской медицинской книжки, теперь называемой санитарная книжка сотрудника, это Health Clearance/Health Certificate и, нет, это не книжка.
Я сам когда-то ратовал за правильные английские названия, но вскоре пришел к выводу: если большая часть разработчиков русскоязычные, то пусть пишут на русском английскими буквами, главное чтобы это было а) понятно и б) чтобы одни и те же понятия разные разрабы называли одинаково (единое понятийное пространство). А для зарубежных коллег, многие из которых, даже владея английским, не владеют терминологией предметной области (тут они ничем не отличаются от "наших") специально выделенный человек пишет пояснения прямо в коде - они очень быстро привыкают.

Если условия позволяют и всем удобно, можно принять за правило и транслит.
Однако мы используем языки и фреймворки, паттерны, термины, которые не принято переводить. Транслитерация тоже по-своему сложна. Я вроде Arsenii по правилам транслитерации, но никогда так своё имя не писал. И всё это вносит неопределённость вместо пользы. А ещё и воспринимается иначе: vykladka vs deployment. Тут же остаётся добавить, что мы читаем документации, статьи, книги на английском (их существенно больше, чем на русском и они свежее). А ещё open source, где с таким подходом не пройдёшь ревью.
Идеальные переводы как недостижимый идеал. Но это не значит, что не стоит к этому стремиться. Это тоже часть порядка. И я бы даже сказал, что единство терминологии > точность перевода.

если вы не 1С пишете, то буквы-то все равно латинские ...

так-то словарик бизнес-терминов все равно будет "имя латиницей - описание на родном языке"

Ну, он как обычно бывает: начинаешь бизнес для своего села, а через несколько лет уже осваиваешь материки. Никогда не знаешь, кто будет работать с кодом. Да, и вообще, я удивляюсь тем, кто в код вбивает свой родной язык.

Ну есть 1с там и язык сам на русском. И названия по русски. Тут такое дело, что имена переменных вплетаются в язык. То есть хорошо читается или "привет, как дела" или "hello, how are you", но не "привет, how дела you"

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

Ещё одна рекомендация — не обсуждайте нейминг текстом (во время ревью или составляя словарик), старайтесь делать это синхронно.

Поясните, плиз. Я не понял эту фразу. Синхронно - это как? Не понимаю как это противопоставляется обсуждения/ревью?

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

Странно... я наоборот придерживался всегда тактики "сохранения следа" - чтобы было понятно, откуда и почему родилось решение, особенно если речь не про то, во сколько сегодня идти на обед, а про что-то важное (а "пространство имён" - по-моему, весьма важный момент). Да, через PR такое футболить - сомнительная идея, но собраться в группе и обсудить с сохранением истории, а если ещё и с посылом "переспать с этим списком" - по-моему, намного продуктивнее "обсудили в курилке"/"пошумели в переговорке".

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

Может быть, подразумевались всякие чаты… такая нечаянная иллюстрация важности нейминга

Как всё таки иногда разражает эти проблемы джунов и синьоров - нейминги, какой фреймфорк использовать и прочие холиварные темы, которые по большей части не имеют смысла. А как доки не так написаны, коммиты не по правилам, а вот доки к тесту не так написаны. Очень сильно раздувает процесс разработки. Все эти придирки к называниям, докам и прочему занимают 95% код ревью. Тогда как по существу на саму логику тратится от 5 до 10, максимум 15% времени, и то 15% я такое не встречал, хотя логика это основа всего, её же практически никто не проверяет. Потому что те же тесты можно так мокировать, что никто не поймёт что программа работает не правильно. Тем более тесты это ручной ввод по типу "2+2" должно быть равно 4. Тут любой алгоритм можно подобрать так что 2+2 будет равно 5, а при должной снаровки можно сделать так что никто ничего не поймёт и тесты будут проходить всегда.

Вообщем действительно есть проблема что саму логику не смотрят и ей почти никогда не уделяют времени, на уровне от джун+ до мидл+, на последних надеются что и так будет работать, насчёт первых не знаю. Но логику подправить никогда практически на это не обращают внимания, уделяя всё внимание неймингу и прочей оболочке. И да рефакторинг это вообще далеко не самая сложная, скорее даже самая простая вещь при должном подходе, переменная которая используется 5, 10, 20 раз меняется за 10-20 секунд вдумчивого подхода.

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

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

Так что если вас волнуют когнитивные усилия читателей, пишите красиво. Если не волнуют, пишите, как хотите.

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

Да и так как не могу сразу написать комментарий то продолжу. Вполне можно потратить день два чтобы привести код в проекте к нормальному состоянию, тем более рефакторинг идёт в 5 - 10 раз быстрее простого написания кода, а если сравнить как я пишу, то и до 100 раз быстрее. Я вот понимаю все концепции солида чистого кода, но не могу не понимаю логику довольно часто, с этим у меня проблемы.

Так вам всего лишь нужно пару раз перечитать и отрефакторить свой собственный комментарий.

Обращу внимание, что статья говорит не только про аккуратность в нейминге. Изменить нейминг через горячие клавиши далеко не всегда удастся. Представьте, что с вашим API взаимодействуют сотни внешних систем. Да даже если десяток — уже сложно. А если одну и ту же переменную использовали для разных целей, потому что не поняли её предназначение?
Избыточные процессы мешают. Но бывает, что проблема в том, что люди выполняют какие-то действия не понимая, для чего это нужно. Статья как раз доносит, почему важно вкладываться в нейминг. Это совсем не nice to have история.
По поводу проверки бизнес-логики во время ревью. Это не лишнее, но, всё же, лучше отладить процессы тестирования. И посмотреть в сторону пирамиды тестирования, где есть не только юнит-тесты.

Переменную не переименовать за 10-20 секунд. Варианты:

  • поле у бд-модели, которое отвечает за столбец

  • по 5 вперёд-назад строчкам непонятно, за что именно она отвечает

  • вызывается где-то в неявном виде ([getattr(smth, f"get_{field}") for field in smth_fields])

  • этот класс используется у третьих сторон через rpc

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

У меня обратный опыт, я больше попадал на доработку реализованных систем, и поэтому меня эти вещи крайне важны. Например, как быстро понять, что за что отвечают условные поля user.tools: integer или car.delivery: char, которые появились с коммитом added new logic? Понять можно, но нужно сначала придётся попрыгать по файлам и поискать по всему проекту (найдите использование поля smth.type в проекте), а затем надеяться, что из-за переименования у пользователей не начнёт дублироваться списание денег.

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

  • вы с самого начала проекта на нём (либо уже давно пришли на него)

  • он не слишком большой, всю логику возможно охватить

  • команда небольшая и вы знаете, кто чем занимается

Если же что-то из этого не работает, то понимать всю логику проекта невозможно, и приходится работать не с логикой, а с контекстом. А в работе с контекстом как раз и помогают те 85+% шелухи - нейминг, коммиты, документация, организация кода, ... .

Я согласен скорее у меня проблема с пониманием и тем что самой логике уделяют крайне мало внимания не более 10% времени. И если ты не знаешь как написать логику то тогда говорят что ты вообще ничего не умеешь. Напротив на обсуждение довольно понятных вещей уходит львинная часть времени любых обсуждений или code review

Насчёт быстрого переименования и имел ввиду что за 20 осмысленных секунд в IDEA или какой либо другой оболочке вы пользуясь методом Рефакторинга можно изменить переменную во всём сервисе. Это как минимум. Про третьи стороны это да, не подходит.

Надеюсь разъяснил. И да у меня не получается понятно выразить свои мысли, извиняюсь у самого с этим проблемы в жизни :(

Варианты:

  • поле у бд-модели, которое отвечает за столбец

  • по 5 вперёд-назад строчкам непонятно, за что именно она отвечает

  • вызывается где-то в неявном виде ([getattr(smth, f"get_{field}") for field in smth_fields])

  • этот класс используется у третьих сторон через rpc

А если где-то в глубине вызовов найдется JSON.serialize(object), то вообще пиши пропало

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

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

После этого полезность правильного нейминга перестанет быть неочевидной.
И про сопроводительный текст для коммитов тоже самое.

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

Один тонкий нюанс, который вы явным образом не затронули: имена всё же бывают слишком длинными. Нейминг из 3-4 слов — это нормально, но не когда все имена такие. Всё же главное в стиле — это лёгкость чтения, и ради него иногда стоит отступиться от педантичной строгости.

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

→ ordersPerCourierLabourHour

Всё-таки лингва франка программистов - это американский английский, так что labor. А ещё лучше - ordersPerCourierManHour.

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

ManHour — гендерно не нейтральный.

Как будто это что-то плохое.

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

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

Ходить в крестовые походы и спорить у кого культура правильная — дело сугубо личное. Можно одно и то же явление рассматривать и как результат эмансипации и как «расчеловечивания». Вопрос этики в разработке интересный. Кто-то делает онлайн-казино, кто-то бы не стал бы. Возможно вопрос нейтральности для вас принципиальный.

А во сколько мужчино-часов вы оцениваете час работы сотрудницы?

Эм, 1? Что мешает сотруднице отработать, согласно вашей же терминалогии, мужчино-час?

Или вопрос задан ради срача?

Всё-таки лингва франка программистов - это американский английский,

А все эти люди об этом знают?

Начните с русского наименования. Совместите значение и название — должно звучать складно, без лишних слов, на которых «спотыкаешься» — как человеческая речь.

Часто каша в понятиях становтся очевидной ещё до того, как вникнешь в предметную область, по чисто формальным признакам

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

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

Справедливо для начала разработки. Но никаких ресурсов не хватит всякий раз решать проблему на корню. Рано или поздно заказчик приходит с очередной идеей, которая не укладывается в ранее заложенные абстракции, а на закладку новых нет времени. И вот тогда вместо специализированного крепежа вы достаёте гвозди / изоленту / клей да идёте обмазывать всё техническим долгом (в том числе имена в коде).

public enum TravelMode // FIXME rename to TransportType
{
Driving = 0, // FIXME rename to Vehicle
Walking = 1, // FIXME rename to OnFoot
Bicycling = 2 // FIXME rename to Bicycle
}
A bicycle, also called a pedal cycle, bike, push-bike or cycle,
is a human-powered or motor-powered assisted, pedal-driven, single-track
vehicle
en.wikipedia.org/wiki/Bicycle

Отлично! Через нейминг увидели, что домен несовершенно спроектирован.
А история там такая, что сначала в енуме было 2 значения, а потом, в одной стране потребовалось выделить велосипедистов отдельно.

Вполне возможно я не прав, но по-моему слишком длинные названия тоже мешают. Такой код сложнее читать. Пока дочитываешь названия, теряешь локальный контекст (я буквально про текущую строку кода и пару соседних). Это про пример из статьи: avgDeliveryOrderFulfillmentTime.

Например:

avgDeliveryOrderFulfillmentTime = superLongVarNameWithAdditionalInfo + anotherOneLongVarName / 2;

И ещё я считаю, что чем меньше область видимости, тем короче могут быть переменные. Нормально же использовать i для цикла. Если функция на 5 строк, то зачем переусложнять (понятно, что иногда бывает нужно, но это исключения).

Добавлю, что читать длинные строки трудно. Вместо того, чтобы читать код в плоскости высота+ширина (и тем более листать вправо), легче воспринимаются более вертикальные, одноразмерные конструкции. IMHO, в примере выше разбиение по строкам несколько помогает.

avgDeliveryOrderFulfillmentTime = superLongVarNameWithAdditionalInfo
                                  + anotherOneLongVarName / 2;

А вообще, тут ещё режет не длина, а отсутствие смысла. Смесь смысла и не-смысла. Если вместо абстрактных superLongVarNameWithAdditionalInfo и anotherOneLongVarName подставить бизнесовые смыслы, внезапно формула становится эмоционально приятнее.

avgDeliveryOrderFulfillmentTime = avgOrderCookingAndPackagingTime
                                  + maxOrderCourierDeliveryTime / 2;

Но в целом, конечно, да. Короткие скоупы -- очень хорошо. Иногда и i имеет право на жизнь, хотя я стараюсь всё-таки писать orderId :)

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

Я использую определения в таком случае. Грубо говоря мой код превращается в

int idx = p_arg; //Index of humanity 

Также стараюсь максимально сжимать контекст используя всякие штуки по кодстайлу. Грубо говоря

class Foo
{
  int ref;
public:
  int& GetRefCount(); 
  int& r_ref();
}; //C++

Где префикс [r_] означает ссылку на объект. В целом читая код понятно что он делает, но вот с "публичным api" приходится возится.

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

> В чём разница между сочинением третьеклассника
> и статьёй в крупном таблоиде?
В сочинении может оказаться правда.

PS: меня как переводчика между несколькими языками и разработчика на ещё нескольких от такого суржика (не путать с терминологией) от подобных текстов малость коробит; искренне желаю научиться говорить красиво, тогда и у кода есть шансы стать красивей.

За пожелание спасибо. Но запрошу конкретику:
что конкретно вызывает коробление?
как бы это звучало красиво?

Да вот прям название статьи (но предназначение «зацепить» оно при этом выполнило :)).

Как думаете — «назови меня тихо по имени» не зацепило бы?

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

Не примите как наезд — докапываюсь тогда, когда вижу смысл, и благодарен многим тем, кто за всю мою жизнь там или сям решил, что есть смысл докопаться по делу в мой адрес :)

С такой стороны я на свой текст не смотрел. Действительно, выразительные средства языка можно использовать лучше. Хотя отсылка к песне Любэ здесь чуть меньше подходит, на мой взгляд. У русского языка мощная система, она переваривает в себе любые заимствования. Как и любой другой язык он живёт и развивается. Когда-то кандидат филологических наук посоветовал мне не переживать по поводу неуместного употребления слова «одел». Если так удобно, то люди так будут говорить и станет это нормой в языке. Возможно и «суржик» так же приживётся. Заимствованные слова — это ведь не всегда аналоги ещё. Многих терминов в нашем языке просто нет. Или они обозначают что-то похожее, но не в точности то же самое.

Как думаете — «назови меня тихо по имени» не зацепило бы?
Не иллюстрировало бы проблему трудностей с неймингом. Вы статьи на Лурке читали? Когда любое явление, если его можно проявить лексически, применяется, собственно, к его описанию. Ну, или, например, слово «ачепятка» — вас тоже коробит?
А в плане именно «зацепило», статья с названием «назови меня тихо по имени» может быть о чём угодно, это название практически не несёт информации. Статья с названием «делай нейминг как сеньор» — точно будет про нейминг в разработке и про проблемы с ним, причём, скорее всего, не самые базовые вещи, очевидные даже джунам. Статьи ни о чём/непонятно, о чём — открывать не хочется. Мало ли о чём оно там будет.

Не стремитесь называть максимально коротко. Нейминг из 3-4 слов — это нормально. Передать конкретику одним словом, чаще всего, нельзя.

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

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

С опытом чувствуешь баланс длина/понятность. Но, пока опыта нет, предпочтительнее длинно, чем непонятно.

Сразу увидел "basket" вместо cart (корзина на сайте)... Эх знали бы ещё эти мудрецы лучше английский 🤦‍♂️

А самое смешное кстати Если зайти в "Basket" то там написано https://s.mail.ru/Vbx8/EYydMoXzx Your Amazon Cart is empty

Это разные предметы:

Отличная статья. Хотелось бы ещё про таксономию в IT почитать.

Никогда не забуду нейминг вида

String[] massiveString

Узнаю свой нейминг! :) Тогда я, после нескольких часов в попытках понять для чего предназначен этот и другие массивы, решил помочь себе хотя бы так. Сейчас понимаю, что решение было опрометчивым.

p.s. потом свои труды передал опытному человеку. Его реакцию трудно передать словами

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

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

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

Да. Несколько, правда, специфично. Вертикальные срезы, под названием "секция". У нас есть особо толстые клиенты, каждый со своей спецификой, ради которых кастомизируется процесс. За каждым таким закреплена отдельная группа. Плюс есть сами по себе специфические секции, которые даже в рамках другого законодательства работают. Под них тоже отдельные люди. Но за этим всем есть ядро системы, которое все это пытается свести в одно и вынуждено с каждым говорить на его языке.

А давайте вспоминать какой кто видел ацкий нейминг. Мой герой это файл в проекте с именем satya.mp3. Satya это имя разработчика запилившего фичу со звуковым файлом.

основной файл стилей назывался temporary_new.css

Не знаю годится это в примеры или нет, но я как-то накопал в могучем легаси, среди костей динозавров метод:

bool isJopa()
{
    return true;
}

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

Как то в довелось ревьють комит, где разработчик написал функцию прохождения по дереву для проверки иерархии. Часть параметров наследовалось от родителя, что было противоположно обычному ходу дел. Так что было важно при наличии такого параметра "убедить" детей. Ну и вот вам мультикультурность - в родном языке разработчика говорят не родительская нода, а нода отец. Так что на английском у него получилась функция с именем: LookAmIYourFather.

Я не удержался и часть ревью выглядела так:

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

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

Давайте конкретнее. Вот RatePerHour - вот как из названия понять - это какой-то промежуточный коэффициент по которому начисляется зарплата или сумма зарплаты в рублях в час?

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

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

Вы всё правильно понимаете. Есть ставка почасовая. Ночью или в праздничные дни применяется повышенный коэффициент, на который умножается ставка. Например коэффициент ночью = 1.2
Да, английский контекстный. Домены помогают однозначно понимать такую терминологию. RatePerHour находится внутри домена Incentives.

var avgWaitingTime = 2000; // FIXME rename to avgHeatedShelfTime

Видно, что писал джуниор, сеньор напишет avgHeatedShelfTimeInMs, ну или использует специальный тип для хранения TimeDelta.

Замечание справедливое, но мы так сознательно сделали. Во всём API возвращаем TimeSpan в секундах и пишем этот момент везде в спецификациях. Внутри системы мы оперируем типом TimeSpan.

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

basketId: 0, // FIXME rename to id

Возможно мой опыт связан с определенными платформами и языками, но я оооочень рекомендую избегать ambiguous naming. Особенно с такими полями как id и name. Иначе обработка полиморфных коллекций и всякие linq будут источником проблем в долгосрочной перспективе. Каждый рефакторинг будет головняком. То же относиться и к запросам в бд. Имя кого и чего почти всегда не понятно из контекста при массовой обработке данных.

Тоже так делаем. Если в объекте есть несколько идентификаторов и имён, то лучше добавить контекста.

Согласен. Меня тоже смутило это. clang-tidy например выдаёт ворнинг если название переменной меньше 3 символов. Зачастую такие поля кладутся в базы данных, где очень удобно делать natural join. Также они могут отправляться по сети, или в названия форм на вебке. Постоянно перекладывать в коде из id в basketId и обратно неудобно. Так же слово basketId удобно делать поиск по всем файлам, включая и код и документацию и csv файлы с данными для тестов. Слово id грепать будет то еще удовольствие.

Зачастую такие поля кладутся в базы данных, где очень удобно делать natural join.

В БД я не эксперт, но даже если там действительно удобнее иметь поле basketId, почему бы не сделать перебрасывание id<->basketId в хранимых процедурах? Как-то странно менять именования в коде приложения ради небольшого удобства DBA.


Также они могут отправляться по сети, или в названия форм на вебке.

А что плохого в отправке json вида {"basket":{"id":1234,...?


Так же слово basketId удобно делать поиск по всем файлам, включая и код и документацию и csv файлы с данными для тестов. Слово id грепать будет то еще удовольствие.

В любом современном редакторе кода можно сделать поиск использований символа. Единственный минус — не найдёт упоминания в комментариях и в коде, тем или иным образом выключенном из проекта.


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

Хранимые процедуры не во всех БД есть, и переименовывать в них что-то это безобразие, такой костыль потом никогда не найдешь.

И идея была не "менять код ради БД" а "именовать сущность везде одинакого, включая код, документацию, БД, и так далее". Даже в Slack если я спрошу какой id у вас застрял, меня не поймут если я не уточню что это basketId.

А причем тут json? Речь была про разные плоские протоколы, где нет объектов.

Впервые слышу про любой современный редактор который умеет искать символ в документации (файле README или еще каком тестовом формате типа Tex), в CSV файлах, в XML файлах. В таких файлах даже человек не сразу поймет про какое id идет речь.

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


Гораздо разумнее определить простые и однозначные правила конвертации имён для тех случаев, где нужна уникальность или другие особые правила именования. Например, для передачи по плоскому протоколу нескольких объектов, на уровне сериализатора добавляйте к каждому полю имя объекта или типа.


Даже в Slack если я спрошу какой id у вас застрял, меня не поймут если я не уточню что это basketId.

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

Спасибо за статью. Забавно, что инвайт на Хабр я получил 10 лет назад именно за статью о нэйминге (https://habr.com/ru/post/207102/). Я уже и сам не согласен с частью правил, которые там озвучил. Но большинству следую и по сей день (да, устав бороться с разработчиками, я ,в итоге, сам стал разработчиком).

Стикеры в тему:

"Нэйминг - это фундамент, на котором возводится небоскреб проекта. "

"Не умеешь в нэйминг - меняй профессию"

"Театр начинается с вешалки, а программирование с нэйминга"

Спасибо, что поделились. Я искал подобные статьи, но слово «именования» для поиска не использовал, поэтому статью не видел. Вот такая ирония про нейминг.

Ирония в том, что слово "нейминг" - это транслитерация, которая является антипаттерном при "нэйминге" :) Поэтому я использовал русское слово "именование" в названии статьи. Но плакат назвал Naming Convention. Ирония в квадрате :)

проблемы с неймингом → проблемы с пониманием предметной области

"Истину глаголишь, боярин" (с). Вот прямо сейчас я вынужден отклонять код ревью по причине не понимания разработчиком предметной области. А всего-то казалось делов: взять нужный ISO стандарт, выделить из него суть, и перенести эту суть в код в виде именованных констант. Но нет.

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

Вопрос к спецам (я не профи, программирую по необходимости в научной работе). У меня часто возникают затруднения (скорее внутренний дискомфорт):

1). слово number в названии переменной можно трактовать, как общее количество чего либо, а можно как порядковый номер?

2). Наименование массивов давать во множественном числе или в единственном? Например при инициализации var shops = [ 'Василёк', 'Ромашка', ... ] — выглядит органично. Но там где обращаюсь к конкретному элементу, выглядит уже странно shops[ i ]. Зато хорошо читается конструкция for ( shop in shops ).

Однако часто вижу использование единственного числа в наименовании массивов в довольно прилично написанном и авторитетном коде. Как правильно?

1) лучше использовать однозначные count и index

По поводу number уже ответили дельно, это специфичное слово, лучше его как «суффикс» не использовать.
По поводу множественного числа, пусть вас не смущает. Например в наименованиях путей в REST очень рекомендуется использовать множественное число: /shops/{id}. Что и в случае с REST, когда у нас есть «каталог» с сущностями, так же и с массивом, который содержит сущности, действует принцип вложенности и отражается в наименованиях.

  1. Общее количество – обычно count или qty. Порядковый номер – index, может еще position.

  2. Или shops, или shopList. Просто shop для массива – имхо, вводит в заблуждение. shops[i] не выглядит странно – это, по сути, "первый из магазинов", "второй из магазинов", вполне органично.

1) количество — можно amount, amt; порядковый номер — ordinal, ord (ну и num тоже видел)
2) нужно во множественном числе: как раз сразу будет понятно, что речь идёт о массиве/списке.

До сих пор помню

`bool _isOnlyTrue = true;`

А как было бы круто если б `bool _isOnlyTrue = false;`

Приходилось видеть всякие константы типа DoNotChangeThisValue с историей изменении чуть ли не каждый день и FirstFunctionToCall где-то в середине списка вызовов в Main... Тот самый вариант бездумного нейминга, когда имя идёт вместо коментария, а смысл и суть функции/переменной остаются загадкой. Просто очередное Magic Value.

Хорошему специалисту (необязательно программисту) необходимы адекватные знания.

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

Про basketId - вот не всегда, особенно если это сущность из базы. В БД часто из-за объединений в таблицах делают явные имена полей и их лучше и в коде такими оставить. Также часто бывает, что тип ид это что-то известное, типа cardId какого то, а сущность типа CartHandler синтетическая, и лучше оставить некоторую избыточность, но узнавабелтность. Но статья хорошая много тем закрывает, но 99% назовут поле с ИНН inn, а не tin и будут правы, если софт для России. Всё же главное это конвенции и простота и однозначность прочтения.

Как правило, для переменных использую общий подход: первые два символа - тип переменной. Следующие два-три символа - "имя" переменной (как правило - бз глснх). Если переменная используется в функции, текст которой помещается на экран целиком - переменные (особенно "временные", и интенсивно используемые) вообще могут быть в одну букву. Такой подход резко сокращает "геометрические" размеры кода. Наверное, я не думаю о будущих поколениях. Но мне нравится так и эта ламповая вкусовщина уходит корнями в прекрасное далёко, когда символами на переменные не разбрасывались.

У вас динамический язык программирования, или IDE не показывает тип переменной? Не совсем понимаю зачем сейчас использовать тип переменной в её названии. Вы не используется минификаторы кода? Зачем так жёстко сокращать имена переменных?

К сожалению или счастью - сейчас практически не приходится пользоваться никакими "продвинутыми" IDE (mc editor и notepad++ - не в счет).

Ооооо, Симонаи ещё помнят :)

Да, точно. Уже и забыл автора!

Часть советов уже применял, но всё равно статья полезная, иногда нужно почувствовать, что делаешь правильно, а не как советуют коллеги. Сомнения только возникают когда получаешь, например, даты диапазона с фронта: start и end, в DateTime преобразую уже в startAt и endAt. Ещё сомневаюсь в правильности использования Get при получении данных. По идее это действие, как Add*, Remove* и др. Но когда методов Get* набирается уже больше десяти, начинаешь задумываться, правильно ли так писать.

StartAt — ’начинать в ’, по-человечески лучше в прошедшем времени. Или мы используем periodFrom, если это фильтр. Просто start для временного отрезка не самый удачный выбор. Да и без разницы фронтенд или бекенд —суффиксы нужны.
Для методов REST есть описанные стандарты.

Статья зашла. Включу "встречу по неймингу" в начало работы. Занимаюсь продуктовой аналитикой, naming convention - это обязательная часть работы по разметке продукта событиями и свойствами.

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

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

Очень рад, что вам пригодилось!

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

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

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

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

Оборачивать библиотеки в свои интерфейсы хорошо: 1) это лишает вас женской привязки 2) добавляет читабельности 3) позволяет спрятать ненужные нам методы.

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

А словарь терминов нужен все равно, причем по доменам. Бывает один и тот же термин в разных предметных областях значит разное. В идеале хочется добиться однозначности названий, но это путь к выдумыванию новых слов и языка, типа как товары Икея называет.

Зарегистрируйтесь на Хабре , чтобы оставить комментарий