[ARCHIVED] Низкоуровневое именование методов/классов/констант

[azinit]

handleClick vs clickHandle?
createUser vs user.create vs userCreate?

---

Методология скорее всего будет рекомендовать нейминг {entity}-{action} (н-р: user-create, post-view, ...) в большинстве случаев

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

Т.е. и при наименовании методов / обработчиков

[sergeysova]

There is a useful pattern to follow when naming functions:

namespace? + high context (HC) + low context? (LC) + action (A)

Take a look at how this pattern may be applied in the table below.

Name	Namespace	High context (HC)	Low context (LC)	Action (A)
userGet		User		Get
userMessagesGet		User	Messages	Get
clickOutsideHandle		Click	Outside	Handle
shouldMessageShown	should	Message		Shown

Note: The order of context affects the meaning of a variable. For example, shouldUpdateComponent means you are about to update a component, while shouldComponentUpdate tells you that component will update on itself, and you are but controlling when it should be updated.
In other words, high context emphasizes the meaning of a variable.

Why action goes the latest?

When you write code in IDE, you have an "code intelligency" or autosuggestion. If you type action first "get", you'll see all function in project that has "get" action, and you need to type High context and Low context to reduce amount of methods.
But if you first type High context you can see all functions that can operate with that context and with lowest contexts, then you can narrow the search typing the Low context name, and now you see all functions you can do with that context and nothing more.

https://gist.github.com/sergeysova/9f6dc24e21efe5f5bb4f9878216c2ce9

[ilyaagarkov]

Я бы подобное обсудил с носителем языка.

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

Аргумент про IDE имеет место быть, но все таки код мы пишем в первую очередь для людей, а не для IDE.
Да это улучшит "code intelligency", но написав get разработчик и так уже знает о каком контексте(HC) идет речь, и в состоянии сам набрать его.

[sergeysova]

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

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

все таки код мы пишем в первую очередь для людей, а не для IDE
Да, как и конвенции нужны людям.

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

Ещё пример: shouldComponentUpdate и shouldUpdateComponent, без конвенции непонятна разница и придется добавлять кучу "мусорных" слов и артиклей для указания принадлежности, как того требует английский(чего мы и так не делаем в большинстве случаев).
С конвенцией всегда понятно, что важнее и как читать такие имена.

Я имею ввиду, что в коде мы НЕ ПИШЕМ на английском, хоть и используем английские слова. Фактически, конвенция выступает своего рода грамматикой для разработчиков, как понимать друг друга в рамках ограничений языка программирования, отсутствия знаков препинания и смысловых акцентов.

[ilyaagarkov]

Почему данный вопрос вообще рассматривается в рамках feature-sliced?
По-моему тут нарушен принцип единой отвественности.

[sergeysova]

С одной стороны кажется, что это out of scope.
Но с другой стороны, у нас всё равно будут рекомендации по именованию фич и entities.

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

[azinit]

@ilyaagarkov, #12 (comment)

[azinit]

WARNING: С этого сообщения и родилась эта холиварня тема

@karina-drummer
Попробую сорировать методы API по типу запроса, но именовать типы согласно CRUD

[azinit]

Two hours later...

@karina-drummer

---

@karina-drummer
Я просто никак не могу понять, зачем в имени каждого метода повторять имя сущности, если можно

api.skins.read.byId()
api.skins.read.list()
api.skins.create.newSkin(

---

@sergeysova
Это в идеале.
Но такую структуру сделать крайне сложно

---

@karina-drummer
А вот напиши, мне нужен конструктив

---

@sergeysova
Гораздо проще сгенерить из сваггера методы, чем глубоко вложенную структуру

Сваггер не позволяет вложенность описать

---

@sergeysova
В сваггере есть только operationId и tags

В итоге имеем
Tag.operationId

Тег нужен для группировки и мы его не юзаем в генераторе. А вот в operationId зашиваем всю нужную инфу

---

@martis-git
Угу, и проблемы в том, чтоб operationId был уникальным для всей схемы

---

@karina-drummer
Я бы правда в таком случае дописывала в конце "Request" для readability, хоть это и муторно

@karina-drummer
Оукей. Если уж так, то может в этом есть смысл
В случае с теми же сагами читается как предложение

---

@sergeysova
Fluent очень тяжело сделать
Особенно с типизацией

---

@sergeysova
В итоге имеем
Tag.operationId

@karina-drummer
А подкиньте хороший пример плиз

---

@karina-drummer
Мы же просто добавляем "Request" в конце имени вообще любого метода

---

@sergeysova
Когда у тебя в начале есть api это смысла не имеет
Это «мусор» как по мне

---

@sergeysova
[скинул api], @martis-git , сможешь переложить это апи на rest crud

---

@martis-git
Ну моей целью было другое донести / узнать)

Не буду расписывать детали, но самое главное, что для нас обоих session.create > [sessionCreate, createSession]

А как там уже между собой будут sessionCreate и createSession воевать - вопрос на будущее)

---

@sergeysova
Там так и показано

---

@karina-drummer
Я всегда стараюсь в декларативный нейминг, то есть не использовать глаголы насколько это возможно, как минимум. Поэтому у меня встречается какой-нибудь api.candidatesListRequest

---

@sergeysova
Только глаголы нужны
А мусор не оч

---

@sergeysova
gist.github.com/sergeysova/9f6dc24e21efe5f5bb4f9878216c2ce9

---

---

Не ребят, я правда задолбался копировать сообщения :DDDD

• про swagger, автогенерацию и tags + operationIds
• про английский язык, читабельность и "неправильные привычки разработчиков"

[sergeysova]

Думаю в следующий раз не надо копировать всё, а только основные доводы)

[azinit]

Думаю в следующий раз не надо копировать всё, а только основные доводы)

Пожалуй, но чет лень было)

Там вся история сообщений настолько красноречива, что решил оставить как есть)

[mindyourlifeguide]

У себя использую event => entities => effect :
getUsersList
updateProfileStatus

вполне удобно и читабельно.

[azinit]

Думаю в следующий раз не надо копировать всё, а только основные доводы)

@sergeysova , схлопнул, темы базово расписал)

[azinit]

@mindyourlifeguide
У себя использую event => entities => effect :
getUsersList
updateProfileStatus

вполне удобно и читабельно.

Очень похоже на то, что описано здесь (да и в большинстве источников)

[azinit]

Ref

@sergeysova
Как я именую всё в приложении.
Когда читаю код, я хочу понимать намерения автора, что он хотел выразить кодом.

Если я вижу функцию employeeStatusChange, я хочу четко понимать её назначение “сменить статус сотрудника” или же “узнать в каком состоянии находится процесс изменения сотрудника”.

Если коротко, то использую подход:
Namespace + HighContext + LowContext + Action

Примеры выше можно показать так (namespace отсутствует):
employeeStatusChange
employee — high context, в контексте чего выполняется действие
status — low context, нечто принадлежащее родительскому контексту
change — action, что делаем с этим
То есть изменяем статус сотрудника.

А вот пример с выяснением текущего статуса процесса изменения сотрудника, может выглядеть так employeeChangeStatus:
employee — high context, всё так же работаем с сотрудником
change — low context, но здесь уже указываем что работаем с сущностью change принадлежащей сотруднику
status — action, выступает как глагол

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

А вот как быть БЕЗ конвенции? Как отличить эти функции не превращая имя в месиво вроде readStatusOfEmployeeChanging, которое не отсортировать по имени, потому что тогда сгруппируются все функции начинающиеся с read*, вместо группирования по сущности employee.

P.S.
Если переложить этот подход на точечную нотацию, получится вполне себе вменяемая объектная модель:
employeeChangeStatus -> employee.change.status()

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

[azinit]

Ref

Конвенции

Natalia

А есть ли способ жить без конвенций? Ну точнее без конвенция помогающих читать что-то непонятное, но с конвенцией как создавать автоматически читабельные имена. Для меня employeeChangeStatus: все равно непонятная хрень. У работника может быть статус и он может меняться, но у работника не может быть изменений, у которых еще и статус есть. Если это замена одного работника на другого, то это статус его вакансии/position (рабочее место в смысле) и выходит на уровень выше, если изменение чего-либо у сотрудника, то у этого чего-либо есть имя и employeeSomethingChange. Проблема в том, что я начинаю об этом думать, и если я сомневаюсь, я лезу в доку читать что мы там наконвентили, потом пытаюсь расшифровать что имелось в виду, хотя должна была непосредственно решать задачу.

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

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

Когда все договорились, что for это цикл, нет никаких проблем понимания кода. Аналогичная ситуация обстоит и с паттернами программирования.

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

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

[azinit]

Ref

Восприятие и Привычка

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

съесть кашу вечером
кашу вечером съесть

@sergeysova
Формальный язык != естественному

Ты не можешь на естественном языке писать код.
Рубисты пытались уже

Aleksandr
Если действий над Кашей много то удобно же

Bohdan
Ну ок)
Если так удобнее - без вопросов)
Для меня глагол останется на своём месте)
...
Я уже выше писал - если тебе норм, то ок, я останусь на старой конвенции.

@sergeysova
Да я ж тебя не заставляю)
Просто лично мне крайне неприятно, что в списке методов все сгруппировано не по сущностям, а по методам.
То есть куча create, потом куча edit и т.д

Bohdan
Я понимаю, но это уже переходит в фючеслайс всего
Методология должно помогать мыслить, а не перестраивать ход моих мыслей под себя

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

Bohdan
на github мне даже ссылочки скинули)
https://github.com/kettanaito/naming-cheatsheet#ahclc-pattern

[azinit]

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

А потому наименования handleOutsideClick vs clickOutsideHandle - выносятся за рамки core-concepts методологии

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

[azinit]

При этом ясно - что эта конвенция применяется и в подходе в какой-то мере

например в доке по Public API

Другой вопрос - насколько готов разработчик упороться доводить этот подход до абсолюта?

[carina-akaia]

call(outsideClickHandler)

[azinit]

Что вам ближе?

Для статистики

Текущие выводы - см. здесь (#12 (reply in thread))

[azinit]

1. Не стремимся за естественным порядком слов, используем свой формальный
2. namespace? + high context (HC) + low context? (LC) + action (A)

• userGet
• userMessagesGet
• clickOutsideHandle
• employeeChangeStatus

[azinit]

1. Начинаем с глагола, как в естественном языке
2. event => entities => effect (условно)

• getUser
• getUserMessages
• handleOutsideClick
• changeEmployeeStatus

[carina-akaia]

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

[azinit]

#12 (reply in thread)

#12 (reply in thread)

@karina-drummer, про то и писал)