5.2 KiB
Соглашения об именовании в 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
Обоснование: Это сильное и общепризнанное соглашение, сигнализирующее о том, что значение является константой.