Я видел не во сне, а наяву атакующие корабли, пылающие под четырьмя вложенными if-else, и лучи CI с кучей сканирований у ворот Тангейзера, вызывающие лютую боль разработчиков. Меня зовут Максим, и я техлид в Газпромбанке.

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

Моё понимание чистого кода: это исходники, каждый файл которых, например, связан с одной зоной ответственности — доменом; методы и классы в нём лаконичны, не расползаются на пять вложенных циклов с ветвлениями. Качественный же код вбирает в себя свойства чистого кода, дополняет их вниманием к техническому исполнению и тестируемостью классов по отдельности.

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

Код для людей

1. Пишите код и тесты так, чтобы они были главной документацией разработчика

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

Как достичь такого «самодокументированного» кода? Начните с постепенного введения Type-Driven Development и тестов бизнес-логики. В случае с Kotlin: делайте sealed class и в нём описывайте все возможные результаты выполнения метода через классы и object’ы.

Вот пример:

data class SubscriberDataUpdate private constructor(
   private val dataUpdate: DataUpdate,
   private val subscriber: Subscriber
) {
 
   val subscriberId: SubscriberId = subscriber.subscriberId
   val dataUpdateId: DataUpdateId = dataUpdate.dataUpdateId
 
   fun prepareUpdateRequest(): Result<SubscriberUpdateRequest> =
       when (isUpdateRequired()) {
           true -> createSubscriberUpdateRequest()
           else -> failNoUpdateRequired()
       }
 
   private fun failNoUpdateRequired(): Result<SubscriberUpdateRequest> =
       Result.failure(RuntimeException("No Update Required"))
 
   private fun createSubscriberUpdateRequest()
           : Result<SubscriberUpdateRequest> =
       Result.success(
           SubscriberUpdateRequest(
               subscriberId.value,
               dataUpdate.msisdn.value,
               dataUpdate.mobileRegionId.value,
               this
           )
       )
 
   private fun isUpdateRequired(): Boolean =
       subscriber.mobileRegionId != dataUpdate.mobileRegionId

    companion object {
       fun emerge(
           dataUpdate: DataUpdate,
           subscriberResult: Result<Subscriber>
       ): Result<SubscriberDataUpdate> =
           subscriberResult.map {
               SubscriberDataUpdate(dataUpdate, it)
           }
   }
 
}

Type Driven в лучах ValueObject

data class SubscriberId
private constructor(
   override val value: String
) : ValueObject<String> {
   companion object {
       fun emerge(subscriberId: String)
               : Result<SubscriberId> =
           when (isStringConsists9Digits(subscriberId)) {
               true -> Result.success(SubscriberId(subscriberId))
               else -> Result.failure(IllegalArgumentException("Subscriber Id consists of numbers maximum length 9"))
           }

       private val isStringConsist9Digits = "^\\d{1,6}\$".toRegex()
       private fun isStringConsists9Digits(value: String) =
           isStringConsist9Digits.matches(value)
   }
}

TESTS

Суть в этом — класс сам себя тестирует:

nternal class SubscriberIdTest {
   @Test
   fun success() {
       val sut = SubscriberId.emerge("888")
       assertThat(sut.isSuccess).isTrue
       assertThat(sut.getOrThrow().value).isEqualTo("888")
   }

   @Test
   fun failWithMoreThen9Digits() {
       val sut = SubscriberId.emerge("1234567890")
       assertThat(sut.isFailure).isTrue
       assertThat(sut.exceptionOrNull()!!.message).isEqualTo("Subscriber Id consists of numbers maximum length 9")
   }

   @Test
   fun failWithWrongFormat() {
       val sut = SubscriberId.emerge("L124S")
       assertThat(sut.isFailure).isTrue
       assertThat(sut.exceptionOrNull()!!.message).isEqualTo("Subscriber Id consists of numbers maximum length 9")
   }

   @Test
   fun failWithWrongFormat2() {
       val sut = SubscriberId.emerge("11aa")
       assertThat(sut.isFailure).isTrue
       assertThat(sut.exceptionOrNull()!!.message).isEqualTo("Subscriber Id consists of numbers maximum length 9")
   }

   @Test
   fun failWithEmpty() {
       val sut = SubscriberId.emerge("")
       assertThat(sut.isFailure).isTrue
       assertThat(sut.exceptionOrNull()!!.message).isEqualTo("Subscriber Id consists of numbers maximum length 9")
   }

}

Нюансы:

• Внедрение Type-Driven Development сопряжено с пусть и небольшими, но затратами.

• Требует перемен в складе мышления.

• Не совсем понятно, что в Type-Driven Development делать с исключениями. Но мы к этому ещё вернёмся.

2. Логи и мониторинг в помощь инженерам

Что лучше — писать логи в какой-то файл где-то на файловой системе или отправлять их в stdout? Отправлять логи строками в Elasticsearch или потратить время на изучение distributed tracing и структурированных логов? Спроектированный с умом мониторинг сокращает время обратной связи и упрощает поиск причины неполадок там, где нет дебаггера под рукой.

Как можно внедрить логи с метриками на примере незамысловатого класса-прослойки для чтения файла. Подключить сбор метрики: alphaMetrica (productId, route).

В коде это будет выглядеть так:

fun dataUpdateProcess(unvalidatedUpdateRequest: UnvalidatedDataUpdateRequest)
       : Mono<Result<SubscriberDataUpdateResponse>> =
   Mono.just(ValidatedDataUpdateRequest.emerge(unvalidatedUpdateRequest))
       .flatMap { findDataWithUpdates(it) }
       .flatMap { findSubscriberForUpdate(it) }
       .flatMap { prepareSubscriberUpdateRequest(it) }
       .flatMap { updateSubscriber(it) }
       .flatMap { sendMetrica(it) }

Всё должно быть прозрачно, очевидно и настраиваемо.

Особенности:

• Делать логи надо такими же читаемыми, как и код, т. е. избегать println («123»).

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

• Или включить в label-метрики URL запроса и таким образом размножить их в Prometheus. В любом из двух случаев вы получите по шапке от соседних команд или руководства.

3. DSL в бизнес-логике: нееш подумой

Доменно-специфичные языки появились сравнительно давно, один из первых популяризаторов DSL — это язык Groovy. С помощью DSL-конструкций можно элегантно и декларативно решать разные задачи, но есть и подводные камни в виде оверхеда лямбд или сложностей проектирования. И да, если вы пытаетесь лечить бойлерплейт в бизнес-логике приложения с помощью DSL или иных декларативных решений, например data-классами в Python (которые с type hints), дважды подумайте. 

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

4. Синтаксические возможности языка и их польза для code quality

Как использовать фичи ЯП и не нарываться на ошибки или code smell? Говоря опять про Kotlin, функции-расширения — это очень здорово, мы в Газпромбанке ими активно пользуемся. И идея с композицией вместо наследования в data-классах мне нравится — всё как Джошуа Блох советует.

Но у каждого языка есть и свои сложные синтаксические решения. Inline-методы с noinline- и crossinline-аргументами тому пример. Или ООП в Python, свойства и геттеры-сеттеры. Как и с DSL, если дело дошло до синтаксических приёмов в бизнес-логике, то остановитесь и задумайтесь, как вы оказались в таком положении.

Как можно делать:

fun <A : Any, B : Any, C : Any> Result.Companion.zip(a: Result<A>, b: Result<B>, c: Result<C>)
       : Result<Tuple3<A, B, C>> =
   if (sequenceOf(a, b, c).none { it.isFailure })
       Result.success(Tuples.of(a.getOrThrow(), b.getOrThrow(), c.getOrThrow()))
   else
       Result.failure(sequenceOf(a, b, c).first { it.isFailure }.exceptionOrNull()!!)

Возможные проблемы:

• Велик соблазн пользоваться языком по полной».

5. ето object. А ето кто?

Речь идёт о null, None, nil, в общем, о нулевых значениях. В принципе, здесь всё просто: не надо, просто не надо писать код с null. Мы решительно не используем null. Только Either<T, ERR>, только хардкор от мира ФП! Или sealed classes (проще говоря, классы с приватным конструктором), в конце концов. Но ещё лучше инкапсулировать данные в классы с бизнес-логикой.

Если вам трудно перейти к полному отсутствию null, начните с полумер, другими словами, внедрите null-safety, Optional’ы и null-checking через «?.». Всяко лучше, чем ничего!

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

6. Гарри Паттерн и кубок кода

Шаблоны проектирования полезны. Мы используем различные паттерны в процессах дизайна кода. Вот лишь часть: ФП, монады, railway-oriented programming (когда код последователен и не перескакивает из места на место). А также мы отказались от исключений. Как? Да просто — через те же sealed classes и Either для описания ошибок как обычных доменных объектов! А не каких-то исключений, которые обрабатываются где-то далеко по стеку.

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

Смотри какое элегантное решение:

fun dataUpdateProcess(unvalidatedUpdateRequest: UnvalidatedDataUpdateRequest)
       : Mono<Result<SubscriberDataUpdateResponse>> =
   Mono.just(ValidatedDataUpdateRequest.emerge(unvalidatedUpdateRequest))
       .flatMap { findDataWithUpdates(it) }
       .flatMap { findSubscriberForUpdate(it) }
       .flatMap { prepareSubscriberUpdateRequest(it) }
       .flatMap { updateSubscriber(it) }

Плюс этого решения с TDD + DDD в том, что он надёжен и прост. Мне, как лиду, легко его контролировать, а разработчику остаётся просто бежать по этому заботливому коридору к ЧистоКоду в конце тоннеля с электроовцами.

Сложности:

• Трудно перестроить свои мозги под мышление паттернами, думать тем же ФП и монадами.

• Перевести всю команду на новую «поваренную книгу» - думал будет труднее, но очень много позитивных отзывов. Опытные разработчики повидавшие еще Великих Гигантов отмечают эту историю как элегантной кодописью.

7. Конфиги мои конфиги

Мы в каком-то смысле поклоняемся постулатам The Twelve-Factor App. 

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

Другой: не использовать группы настроек, поскольку так можно получить комбинаторный взрыв из сочетаний, — про логику слияния и переопределения параметров я вообще молчу. Поэтому не усложняйте себе жизнь — используйте самое простое решение, environment variables!

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

rest:
 services:
   subscribers:
     url: http://localhost:8080 #wireMock me local
     updates: /api/v1/subscribers/updates/{dataUpdateId}
     subscribers: /api/v1/subscribers/{subscriberId}

И в тестах:

rest:
 services:
   subscribers:
     url: http://localhost:${wiremock.server.port} #wireMock me local

wiremock:
 server:
   port: 4567

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

8. Выбирайте фреймворки правильно. А что там, на заборе, написано?

При открытии какого-то перечня веб-фреймворков из абстрактного awesome-list вам может показаться — вот оно, в этом фреймворке решены все проблемы человечества! 

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

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

Код для машин

9. Делайте тесты. А как ка… тестировать?

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

Писать с TDD проще, чем кажется: просто попробуйте писать сначала гипотетические тесты перед кодом. Если не получается — подумайте, каким кодом вы бы хотели пользоваться.

10. CI/CD в помощь команде

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

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

Если в целом, то советую начинать CI/CD с автотестов и потом уже внедрять линтеры, анализ кода и анализ зависимостей.

11. Преждевременная оптимизация

Не налегайте слишком на оптимизации в сервисе, ведь вы можете навредить качеству кода, причём сильно. Могу предложить делать оптимизации красиво — так, чтобы это соответствовало гайдлайнам и best practices фреймворка, но для этого нужен навык. При этом некоторые оптимизации можно сделать, даже немного приукрасив кодовую базу: например, паттерны пагинации, batch processing или потоковой обработки могут и оптимизировать код, и сделать его в чём-то понятнее.

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

Это всё наша команда извлекла из своих уроков жизни и программирования. А какие приёмы и советы знаете вы? Приглашаем в комментарии!