# Соглашения об именовании в Kotlin для AI

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

## 1. Общий принцип: Ясность и Описательность

**Правило:** Имена ДОЛЖНЫ быть описательными и четко сообщать о назначении переменной, функции, класса или другой конструкции. Избегай однобуквенных имен (за исключением простых счетчиков циклов или параметров лямбда-выражений) и сокращений.

**Действие:**
- **Хорошо:** `val userProfile = getUserProfile()`
- **Плохо:** `val u = getUP()`
- **Хорошо:** `fun sendEmailToPrimarySubscriber()`
- **Плохо:** `fun email()`

**Обоснование:** AI в значительной степени полагается на имена для вывода смысла и назначения кода. Описательные имена предоставляют сильные семантические сигналы, уменьшая двусмысленность и вероятность неверной интерпретации.

## 2. Имена пакетов

**Правило:** Имена пакетов ДОЛЖНЫ быть в `lowercase` и не должны использовать подчеркивания (`_`) или другие специальные символы. Несколько слов должны быть соединены вместе.

**Действие:**
- **Хорошо:** `com.homebox.lens.user.profile`
- **Плохо:** `com.homebox.lens.user_profile`

**Обоснование:** Это стандартное соглашение в мире Java и Kotlin. Его соблюдение обеспечивает консистентность.

## 3. Имена классов и интерфейсов

**Правило:** Имена классов и интерфейсов ДОЛЖНЫ быть в `PascalCase`.

**Действие:**
- **Хорошо:** `class UserProfile`
- **Хорошо:** `interface UserRepository`
- **Плохо:** `class user_profile`

**Обоснование:** `PascalCase` является стандартом для типов. Это позволяет AI немедленно отличать типы от переменных или функций.

## 4. Имена функций

**Правило:** Имена функций ДОЛЖНЫ быть в `camelCase`. Обычно они должны быть глаголами или глагольными фразами.

**Действие:**
- **Хорошо:** `fun getUserProfile()`
- **Хорошо:** `fun calculateTotalPrice()`
- **Плохо:** `fun UserProfile()`
- **Плохо:** `fun total_price()`

**Обоснование:** `camelCase` является стандартом для функций. Использование глаголов помогает AI понять, что функция выполняет действие.

## 5. Имена переменных и свойств

**Правило:** Имена переменных и свойств ДОЛЖНЫ быть в `camelCase`.

**Действие:**
- **Хорошо:** `val userName: String`
- **Хорошо:** `var isVisible: Boolean`
- **Плохо:** `val UserName: String`
- **Плохо:** `val is_visible: Boolean`

**Обоснование:** Консистентность с именами функций.

## 6. Имена для Boolean

**Правило:** Имена для `Boolean` переменных или функций, возвращающих `Boolean`, ДОЛЖНЫ начинаться с глаголов "is", "has" или "should".

**Действие:**
- **Хорошо:** `val isVisible: Boolean`
- **Хорошо:** `fun hasPendingChanges(): Boolean`
- **Плохо:** `val visible: Boolean`
- **Плохо:** `fun pendingChanges(): Boolean`

**Обоснование:** Это соглашение делает булеву логику намного яснее и менее двусмысленной для AI. Имя читается как вопрос, чем, по сути, и является булево условие.

## 7. Имена констант

**Правило:** Константы (свойства, определенные в `companion object` или свойства верхнего уровня с `const val`) ДОЛЖНЫ быть в `UPPER_SNAKE_CASE`.

**Действие:**
- **Хорошо:** `const val MAX_RETRIES = 3`
- **Плохо:** `const val maxRetries = 3`

**Обоснование:** Это сильное и общепризнанное соглашение, сигнализирующее о том, что значение является константой.