Codestyle

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

Основной фокус, в первую очередь, на жестких правилах, которым следуют Google разработчики повсеместно!

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

Поэтому я решил разделить её на две части.

Обе части содержат описание стандартов кода на языке прораммирования Kotlin.

Что покрывают обе части:

• Именование файлов, переменных, классов, свойств и т.д.

• Структура исходного файла

• Форматирование - строки, пробелы, скобки, специальные конструкции, переносы и др.

• Документация

В первой части я затрону исходные файлы и форматирование (неполностью).

Ну что ж пора начинать!

Исходные файлы

Поговорим сначала об исходных файлах, о их структуре и других важных вещах.

Кодировка

Все исходные файлы должны иметь UTF-8 кодировку.

Именование

Все исходные файлы, которые содержат высокоуровневые определения классов, должны именоваться следующим образом: имя класса + расширение файла .kt

Если файл содержит несколько высокоуровневых определений (два класса и один enum к примеру) выбирается имя файла, которое описывает его содержимое:

// PhotoAdapter.ktclass PhotoAdapter(): RecyclerView.Adapter<PhotoViewHolder>() {// ...}// Utils.ktclass Utils {}fun Utils.generateNumbers(start: Int, end: Int, step: Int) {// ...}// Map.ktfun <T, O> Set<T>.map(func: (T) -> O): List<O> = // ...fun <T, O> List<T>.map(func: (T) -> O): List<O> = // ...

Структура

Kotlin файл .kt включает в себя:

• Заголовок, в котором указана лицензия и авторские права (необязательно)

• Аннотации, которые объявлены на уровне файла

• package объявление

• import выражения

• высокоуровневые объявления (классы, интерфейсы, различные функции)

Заголовок должен быть объявлен выше остальных определений с использованием многострочных комментариев:

/* * Copyright 2021 MyCompany, Inc. * * */

Не используйте однострочные и KDoc комментарии:

/**  * Copyright 2021 MyCompany, Inc. * */// Copyright 2021 MyCompany, Inc.//

Аннотация @file, которая является use-site target должна быть помещена между заголовком и package объявлением:

/* * Copyright 2021 MyCompany, Inc. * */@file:JvmName("Foo")package com.example.android

Оператор package и importникогда не переносятся и всегда размещаются на одной строке:

package com.example.android.fragments  // переносы запрещеныimport android.view.LayoutInflater // так же и здесьimport android.view.View

Выражения import группируются для классов, функций и свойств в сортированные списки.

Импорты с подстановочным знаком не разрешены:

 import androidx.room.*  // так делать не нужно

Kotlin файл может содержать объявление одного или нескольких классов, функций, свойств или typealias выражений.

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

Нет явного ограничения на количество и порядок содержимого файла

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

Важен логический порядок, который может объяснить сам разработчик.

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

Для членов класса применимы те же правила, что и для высокоуровневых определений.

Специальные символы

В исходном коде используется только ASCII горизонтальный пробельный символ (0x20).

Это означает, что:

• Все другие пробельные символы в строчных и символьных литералах должны экранироваться

• Tab символы не используются для отступов

Для любого символа, который имеет экранированную последовательность (\b, \r, \t, \\) используется эта последовательность, а не Unicode (например: \u000a).

Для оставшихся символов, которые не принадлежат ASCII, используется либо Unicode символ (), либо Unicode последовательность (\u221e).

Выбор зависит лишь от того, что облегчает чтение и понимание кода:

// Лучшая практика: понятно без комментариевval symbol0 = ""// Плохо: нет причины не использовать символ вместо Unicode последовательностиval symbol1 = "\u221e" // // Плохо: читатель не сможет понять, что это за символ val symbol2 = "\u221e"// Хорошо: использование Unicode последовательности для непечатаемого символаreturn "\ufeff" + content// неразрывный пробел нулевой ширины

Форматирование

Ближе к коду!

Скобки

Скобки не требуются дляwhen и if которые помещаются на одной строке (оператор if не имеет else ветки):

if (str.isEmpty()) returnwhen (option) {    0 -> return    // }

В другом случае скобки обязательно требуются для if, for, when ветвлений и do и while выражений:

if (str.isEmpty())    return  // так делать нельзя!if (str.isEmpty()) {    return  // OK}

Скобки следуют стилю Кернигана и Ритчи для непустых блоков и блочных конструкций:

• Нельзя делать разрыв строки перед открывающей скобкой

• Разрыв строки после открывающей cкобки

• Разрыв строки перед закрывающей скобкой

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

class MainActivity : AppCompatActivity() {    private lateinit var binding: ActivityMainBinding    override fun onCreate(savedInstanceState: Bundle?) {        super.onCreate(savedInstanceState)        binding = DataBindingUtil.setContentView(this, R.layout.activity_main)        // ...    }}

Пустые блоки тоже должны быть в стиле K&R:

try {    val response = fetchDogs("https://api.dog.com/dogs")} catch (e: Exception) {} // неправильноtry {    val response = fetchDogs("https://api.dog.com/dogs")} catch (e: Exception) {} // OK

if/else выражение может быть без скобок, если помещается на одной строке:

val value = if (str.isEmpty()) 0 else 1  // OKval value = if (str.isEmpty())// неправильно0else1val value = if (str.isEmpty()) { // OK0} else {1}

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

Переносы

Каждое выражение разделяется переносом на новую строку (; не используется)

Строка кода имеет ограничение в 100 символов.

Исключения:

• Строки, которые невозможно перенести (например: длинный URL)

• package и import выражения

• Команды в документации, которые можно вставить в shell

Правила для переноса на новую строку:

• Перенос после оператора или infix функции.

• Если строка завершается следующими операторами, то перенос осуществляется вместе с ними:

  • точка (., .?)

  • ссылка на член (::)

• Имя метода или конструктура находится на одной строке с открывающей скобкой

• Запятая (,) связана с элементом и не переносится

• Стрелка (->) для lambda выражений связана с аргументами

Когда сигнатура функции не помещается, объявление параметров располагается на отдельных строчках (параметры должны иметь один отступ в 4 пробела):

fun makeSomething(  val param1: String,  val param2: String,  val param3: Int) {}

Когда функция содержит одно выражение можно сделать так:

override fun toString(): String {return "Hello, $name"}override fun toString() = "Hello, $name"

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

fun waitMe() = runBlocking {delay(1000)}

Когда инициализация свойства не помещается на одной строке можно сделать перенос после знака присваивания (=):

 val binding: ListItemBinding =  DataBindingUtil.inflate(inflater, R.layout.list_item, parent, false)

get и set функции должны быть на отдельной строке с обычным отступом (4 пробела):

 val items: LiveData<List<Item>> get() = _items

Read-only свойства могут иметь более краткий синтаксис:

val javaExtension: String get() = "java"

Пробелы

Пустая строка может быть:

• Между членами классов: свойствами, функциями, конструкторами и другими

  • Пустая строка между двумя свойствами необязательна. Это нужно для создания логических групп (например для backing свойств)

• Между выражениями для логического разделения

• Перед первым членом функции или класса (необязательно)

Помимо требуемых правил для языка и литералов (строчных или символьных) одиночный ASCII пробел:

• Разделяет зарезервированные слова, таких как: if, for или catch от круглой открывающей скобки:

// неправильноfor(i in 1..6) {}// OKfor (i in 1..6) {}

• Разделяет любые зарезервированные слова, таких как else и catch от закрывающей фигурной скобки:

// Неправильно}else {}// OK} else {}

• Ставиться перед любой открывающей фигурной скобкой:

// Неправильноif (items.isEmpty()){}// OKif (items.isEmpty()) {}

• Ставиться между операндами:

// Неправильноval four = 2+2// OKval four = 2 + 2// Это относится и к оператору лямбда выражения (->)// Неправильноitems.map { item->item % 2 == 0 }// OKitems.map { item -> item % 2 == 0 }

• Исключение: оператор ссылка на член (::), точка (.) или range (..)

// Неправильноval str = Any :: toString// OKval str = Any::toString// Неправильноitem . toString()// OKitem.toString()// Неправильноfor (i in 1 .. 6) {println(i)}// OKfor (i in 1..6) {println(i)}

• Перед двоеточием (:) для указания расширения базового класса или интерфейса, а также в when выражении для generic типов:

// Неправильноclass Worker: Runnable// OKclass Worker : Runnable// Неправильноfun <T> min(a: T, b: T) where T: Comparable<T>  // OKfun <T> min(a: T, b: T) where T : Comparable<T>

• После двоеточия (:) или запятой (,)

// Неправильноval items = listOf(1,2)// OKval items = listOf(1, 2)// Неправильноclass Worker :Runnable// OKclass Worker : Runnable

• По обеим сторонам двойного слеша:

// Неправильноvar debugging = false//отключен по умолчанию// OKval debugging = false // отключен по умолчанию

Заключение

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

В следующей статье: именование, специальные конструкции и документация.

Полезные ссылки:

• Kotlin style guide (на английском)

• K&R стиль

• Книга: Чистый код (Боб Мартин)

• Кратко о книге Боба Мартина

Ждите следующей части!

В принципе, я согласен с комментариями, что данная тема излишняя, так как существуют автоматические инструменты форматирования кода

И к тому же у каждого своё мнение о красоте и эстетичности, поэтому coding style носит субъективный характер.

Но я все таки решил закончить данную серию статей по Kotlin стилю, как и обещал.

Возможно кому-нибудь пригодится.

Ну что ж прошу под кат!

Именование

Идентификаторы переменных, функций, свойств, классов используют только ASCII буквы и цифры (обычные английские буквы + 10 цифр)

Специальные суффиксы или префиксы (например: _digit, power_) не используются (исключение: Backing свойства).

Имена функций

Начнем с именования функций.

Основное правило: имя функции должно быть написано в верблюжьем стиле (например: fetchDogs) и быть глаголом (makeRepost)

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

@Test fun get_emptyList() {  // ...}

Функции, которые аннотированы @Composable (Jetpack Compose смотрите здесь) носят имена, которые являются существительными, отформатированными в Pascal стиле:

@Composablefun MyDog(name: String) {    // }

Именование констант

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

Константы в Kotlin - это val свойства, которые не имеют кастомного оператора доступа get, а их контент является неизменяемым. Сюда относятся: неизменяемые коллекции и типы

(listOf(1, 2, 3)), а также скалярные типы, помеченные ключевым словом const:

// константы для скалярных типов должны быть объявлены с помощью constconst val FIVE = 5val MY_DOGS = listOf("Dina", "Red")val EMPTY_ARRAY = arrayOf()

Константы могут быть объявлены внутри конструкции object или как высокоуровневые определения (на уровне файла).

На константы, которые объявлены на уровне класса, данные правила именования не распространяются.

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

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

val viewModel by viewModels<DogViewModel> { viewModelFactory }val firstName = "Anna"val dogs = listOf(Dog("Dina"), Dog("Red"))lateinit var binding: ListItemBindingfun fetchDogs(page: Int): List<Dog> {// ...}                                                                  

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

    private val _dogs = MutableLiveData<List<Dog>>()    val dogs: LiveData<List<Dog>>        get() = _dogs

Имена generic типов должны соответствовать одному из стилей:

• Одна заглавная буква (можно добавить одну цифру, например: T1, T2, R1)

• Имя generic типа, который используется для класса может состоять из имени класса и дополнительного суффикса T (например: RequestT, ResponseT)

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

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

Имена классов записываются в Pascal стиле (например: SleepingDog - каждое слово начинается с заглавной буквы).

Также они являются существительными или фразами (например: MyCar - состоит из двух слов)

Интерфейсы именуются по тем же правилам. Как дополнение они могут быть прилагательными (например: Cloneable, Readable, Writable):

class MainActivity(): AppCompatActivity() {  // ...}interface OnItemListener {fun onItemClick(id: Long)}interface Readable {}

Именование пакетов

Здесь ничего особеного: имена пакетов находятся в нижнем регистре и не содержат никаких нижних подчеркиваний:

// Неправильноpackage com.example.android.marsRealeState.overview// Неправильноpackage com.example.android.mars_reale_state.overview// OKpackage com.example.android.marsrealestate.overview

Специальные конструкции

Константы enum классов могут быть размещены на одной строке:

enum class NetworkStatus {   SUCCESS, FAILED, LOADING } 

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

enum class NetworkStatus {  SUCCESS,  FAILED,    LOADING {  override fun toString() = "loading..."   }}

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

Что касается аннотаций, здесь правила предельно простые:

// аннотации размещаются на отдельных строчках @Singleton@Component(modules = [DatabaseModule::class])interface AppComponent {  // ...}// если аннотации не имеют параметров, то можно впихнуть их в одну строку@JvmField @Volatilevar disposable: Disposable? = null// если у вас одна простая аннотация то можно вот так:@Inject lateinit var viewModelFactory: DogViewModelFactory

Также возможен вариант более лаконичного синтаксиса для объявления переменных и функций:

// вместоoverride fun toString(): String = "My name is $name"// можноoverride fun toString() = "My name is $name"// вместоprivate val redDog: Dog = Dog("Red")// можноprivate val redDog = Dog("Red")

Документация

Базовое форматирование KDoc выглядит следующим образом:

/** * Здесь пишем документацию *  */fun fetchDogs(page: Int) {    // }

Если строка очень маленькая её можно уместить на одной строке:

/** Очень короткая строка моей документации */

Основные правила форматирования документации:

• Используйте пустую строку, которая содержит только звездочку (*), чтобы разделять отдельные абзацы

• Любые из стандартных блоков идут по порядку: @constructor,@receiver,@param,@property,@return,@throws,@seeи не могут быть пустыми

• Каждый KDoc блок начинается со специального фрагмента, которые содержит основную информацию о классе или функции (например: "This function returns sum of digits"). Обычно это неполное предложение

Как минимум, KDoc документация используется для публичных методов, классов, полей, то есть public API.

Для простых функций документацию можно не писать при условии, что они настолько простые, что их легко прочитать:

// Полагаю, не требует объяснений.fun sum(a: Int, b: Int) = a + b

А вот, например, такие нетривиальные вещи, как функция нахождения определителя матрицы требует дополнительных разъяснений.

Исключение: KDoc документация не всегда присутствует в методе, который переопределяет метод из суперкласса.

Заключение

Эта статья завершает мой небольшой цикл.

Возможно я выбрал эту тему, потому что мне нечего делать, а возможно я просто хотел понять: стоит ли замарачиваться такими вещами, как форматирование кода, если есть встроенные инструменты Android Studio, которые сделают это лучше меня по всем правилам!

Я хотел бы попросить читателей о небольшой просьбе: написать комментарий "на какую тему вы бы хотели прочитать статью по Android разработке?"

Полезные ссылки:

1. Официальное руководство по Kotlin стилю (на английском)

2. Backing свойства

3. Generic типы

4. Jetpack Compose

5. Документирование Kotlin кода (на английском)

6. Дополнительная информация на Википедии

Довольно часто сталкиваюсь с вопросом касательно качества кода: "Почему написано именно так, а не так?". И я объясняю каждый раз. Именно поэтому решил составить эдакую заметку с некоторыми примерами и объяснениями.

Второй возникающий вопрос: "Где научился так красиво писать?". Ответ на который будет к концу статьи.

Приведу три примера, с которыми сталкиваюсь чаще всего.

Пример 1

use App\Models\Payment;use Illuminate\Database\Eloquent\Model;class Foo extends Model {  public function user(){    return $this->hasOne('App\Models\User');  }  public function payments(){    return $this->hasMany(Payment::class);  }}

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

Начнём с того, что открывающиеся фигурные скобки лучше переносить на новую строку. Это позволит сделать код более приятным в чтении (Привет, PSR-12).

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

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

class Foo{    public function user()    {        //    }}

То у другого он может быть таким:

class Foo{        public function user()        {                //        }}

Или таким:

class Foo{  public function user()  {    //  }}

Согласитесь, разница ощутима. А символ "пробела" он и в Африке символ "пробела", отображающийся на всех устройствах одинаково.

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

Итак, после ревью код будет выглядеть так:

use App\Models\Payment;use App\Models\User;use Illuminate\Database\Eloquent\Model;class Foo extends Model{    public function user()    {        return $this->hasOne(User::class);    }    public function payments()    {        return $this->hasMany(Payment::class);    }}

Пример 2

Недавно встретил такой участок кода (вставлю картинкой, чтобы не нарушить его вид):

Даже не буду говорить о существовании паттернов - скажу лишь о том, что ООП было придумано для сокращения дубляжа кода, но...

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

Проведём код-ревью:

class NewsService{    public function sendNews(EmployerNews $employerNews)    {        $this->dispatch($employerNews, WorkPositionIdsJob::class);        $this->dispatch($employerNews, WorkPositionTypesJob::class);        $this->dispatch($employerNews, EmployerIdsJob::class);    }    protected function dispatch(EmployerNews $news, string $class): void    {        $job   = $this->job($news, $class);        $delay = $this->delay();        dispatch($job)->delay($delay);    }    protected function job(EmployerNews $news, string $job): AbstractJob    {        return new $job($news->getAttributes());    }    protected function delay(): Carbon    {        return Carbon::now()->addSecond();    }}

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

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

То же самое касается и примерно таких проблемных участков, как:

switch($value){    case 'foo':        //        break;    case 'bar':        //        break;}

if ($employerPriceCategory->default) {    return false;}$defaultCategory = EmployerPriceCategory::where('default', true)    ->first(['id']);Employer::query()    ->where('employer_price_category_id', $employerPriceCategory->id)    ->update([        'employer_price_category_id' => $defaultCategory->id,    ]);

$districts = $this->getDistricts();$this->output->writeln('districts: ' . sizeof($districts));$period = $this->getPeriod();foreach ($period as $start) {    $end = $start->copy()->endOfDay();    $this->output->writeln('date = ' . $start->format('Y-m-d'));    //}

Это же просто ужас! Как такое вообще можно читать? А писать?!

Давайте отрефакторим их!

switch($value){    case 'foo':        //        break;    case 'bar':        //        break;}

if ($employerPriceCategory->default) {    return false;}$defaultCategory = EmployerPriceCategory::query()    ->select(['id'])    ->where('default', true)    ->first();Employer::query()    ->where('employer_price_category_id', $employerPriceCategory->id)    ->update(['employer_price_category_id' => $defaultCategory->id]);

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

Пример 3

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

Логический блок - это участок кода состоящий из нескольких строк, объединённых между собой какой-либо общей чертой.

Для примера возьмём следующий участок:

$salaryFirstBaseEmployer = $employer->salaryBases->first()->salary_base;$salaryLastBaseEmployer = $employer->salaryBases->last()->salary_base;$begin = Carbon::parse('2020-05-01')->startOfMonth()->startOfDay();$end = $begin->clone()->endOfMonth()->endOfDay();$endMonth = $begin->clone()->endOfMonth();$startPeriod = new CarbonPeriod($begin, $end);$endPeriod = new CarbonPeriod($begin, $end);

В нём мы видим непонятный массив текста. Отформатируем его, разбив на логические блоки:

$salaryFirstBaseEmployer = $employer->salaryBases->first()->salary_base;$salaryLastBaseEmployer  = $employer->salaryBases->last()->salary_base;$begin = Carbon::parse('2020-05-01')->startOfMonth()->startOfDay();$end      = $begin->clone()->endOfMonth()->endOfDay();$endMonth = $begin->clone()->endOfMonth();$startPeriod = new CarbonPeriod($begin, $end);$endPeriod   = new CarbonPeriod($begin, $end);

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

Заключение

Очень давно мне дали дельный совет:

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

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

Каждая статья с критикой PHP, следом за объяснением почему $ в обозначении переменной портит синтаксис, обязательно расскажет вам о том, как плохо организовано именование функций в ядре и расширениях. И если $ останется в стандарте языка и наших сердцах навсегда (хотя бы просто как напоминание о старом-добром PHP), то с именованием функций давно пора что-то делать.

Standard PHP Library

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

Standard PHP Library (SPL) уже существует в качестве отдельного расширения. SPL предоставляет структуры данных, исключения, итераторы и многое другое, но к базовым функциям, например к функциям для работы со строками, никакого отношения не имеет. Они, на мой далёкий от устройства интерпретатора PHP взгляд, просто существуют где-то в ядре и являются как бы частью стандарта языка.

Я считаю, что базовые функции следует выделить в отдельное расширение и самым подходящим для него названием стало бы именно Standard PHP Library.

Проблемы

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

Наиболее заметные проблемы:

1. одновременно существуют несколько подходов к именованию: с префиксом str_ (str_split), с префиксом str (strrev), с префиксом substr_ (substr_compare), без какого-либо префикса (trim);

2. однородные функции имеют аргументы с разными именами, например, в strncmp два аргумента: str1 и str2, в strnatcasecmp: string1 и string2, а в substr_compare: haystack и needle;

3. однородные функции имеют разный порядок следования однородных же аргументов все помнят историю про порядок аргументов в implode и explode;

4. совершенно нечитаемые и непроизносимые имена функций: strtr, strncmp, strpbrk, strrchr и т.д.;

5. некоторые функции могут менять тип возвращаемого значения в зависимости от типов переданных им аргументов, например, substr_replace непринужденно жонглирует массивами и строками;

6. зачастую функции возвращают false в случае ошибки или неверно заданных аргументов, например, strrpos;

7. некоторые функции выглядят довольно экзотично и используются крайне редко: soundex, levenshtein и т.д.

Причины

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

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

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

Что я предлагаю

Выделить функции из состава ядра в отдельные расширения

Отдельные расширения проще тестировать и их релизы можно выпускать отдельно от больших релизов языка. Здесь я ничего нового не скажу преимущества модульности давно известны.

Добавить пространства имен для расширений

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

Я не буду выдумывать что-то новое и просто использую PSR-4. В качестве имени вендора очевидно следует использовать Php, а дальше добавить имя расширения. Таким образом, будущие функции стандартной библиотеки будут в пространстве имен Php\Spl.

Договориться о правилах именования функций и аргументов

Снова предлагаю существующие стандарты: частично использовать PSR-12 и частично правила именования функций от дядюшки Боба.

1. Имена функций не должны содержать какого-либо явного префикса расширения, в котором определены. Иными словами, не должно быть никаких str_ или str, для этих целей служит пространство имен.

2. Имена функций и аргументов должны быть заданы в lowerCamelCase.

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

4. Имена аргументов также должны быть читаемыми и содержать в себе явное описание передаваемых данных. Уместно использовать в качестве имен аргументов существительные.

5. Порядок и имена аргументов для однородных функций, например для функций сравнения строк, должны совпадать.

Включить строгую проверку типов данных

Тут давно пора навести порядок. Например sscanf может возвращать массив, целочисленный результат или null. Я уверен, что взрослый язык может позволить себе согласовать типы аргументов и возвращаемых значений для функций стандартной библиотеки.

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

1. Функции стандартной библиотеки должны использовать строгую проверку типов аргументов и возвращаемых значений.

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

3. Для аргументов допустимо использовать union-типы и nullable-типы.

4. Возвращаемое значение должно иметь один явный тип или быть null там, где это оправданно.

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

Практическая реализация

В качестве proof of concept я создал библиотеку, которая следует всем правилам, указанным выше, и предлагает новые имена функций для работы со строками https://github.com/marvin255/php-spl-proposal/blob/master/src/StringUtilities.php.

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

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

Пара примеров для ознакомления.

strnatcmp(test1, test2);// заменяется наStringUtilities::compareUsingNaturalOrder(test1, test2);

str_contains(test, t);// заменяется наStringUtilities::isContain(test, t);

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

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

Вместо заключения

Статья не претендует на какую-либо объективность. Более того, очевидно, что я не смог за пару вечеров исправить один из коренных недостатков PHP.

Я вижу как данную проблему из релиза в релиз обходят стороной в погоне за новыми фичами и синтаксическим сахаром. Не подумайте, я не имею ничего против изменений, введенных в PHP 7 и 8, но и для возвращения технического долга нужно найти время.

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