russian-developer-style

name

russian-developer-style

description

Russian style guidance for developer-facing text of any length — README and docs, code comments, docstrings, commit messages, PR descriptions, changelog entries, UI strings (buttons, labels, placeholders, tooltips), error and log messages, and localisation files (.po, .properties, JSON i18n). Use whenever the task involves Russian developer text — writing, editing, rewriting, translating, localising, reviewing, proofreading, verifying, auditing, double-checking, sanity-checking, cross-checking. Trigger verbs include the Russian "напиши", "переведи", "локализуй", "проверь", "перепроверь", "сверь", "отревью". Length does not matter: a one-line `msgstr` is in scope. Focuses on clear natural Russian, technical precision, terminology consistency, and avoiding bureaucratic or LLM-like phrasing.

Русский стиль для developer-текста

Скилл задаёт стиль русскоязычного текста для разработчиков и для пользователей программ: документация и README, комментарии и docstring, сообщения коммитов, описания PR, changelog, UI-строки, сообщения об ошибках и логи, файлы локализации (.po, .properties, JSON i18n). Длина не важна: однострочный msgstr — тоже в зоне действия скилла. Скилл не управляет кодом, маркетинговыми материалами и художественной прозой.

Базовые установки: спокойный технический голос, вежливое строчное «вы» (или безличные обороты, где они естественнее), настоящее время, заголовки в стиле обычного предложения, единый стиль терминологии. Образ автора: коллега, который уже решал эту задачу и объясняет коротко.

Главная задача скилла — переписывать LLM-черновики и переводы так, чтобы они звучали по-русски, не теряя технической точности.

1. Когда применять

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

Триггерные действия:

• Создание: пишете новые страницы документации, README, комментарии, сообщения коммитов, описания PR, changelog, UI-строки, тексты ошибок и логов.
• Перевод и локализация: переводите английский интерфейс, документацию или сообщения на русский; правите файлы .po, .pot, .properties, .resx, JSON i18n, Fluent.
• Редактура: переписываете LLM-черновик перед коммитом (основной режим), правите чужой текст.
• Ревью и проверка: «проверь перевод», «перепроверь сообщения», «сверь с оригиналом», «отревью PR», «правильно ли переведено», «посмотри, насколько естественно звучит». Сюда же — аудит переводов, написанных людьми.

Поверхности, которые покрывает скилл:

• Markdown: README, документация, design docs, ADR, changelog, release notes.
• Файлы локализации: .po, .pot, .properties, .resx, JSON i18n, .ftl, .arb. Однострочный msgstr — тоже в зоне действия.
• UI-строки: кнопки, подписи, плейсхолдеры, tooltips, пустые состояния, подтверждения.
• Сообщения об ошибках, валидациях, варнингах и логах.
• Комментарии в коде, docstring, Javadoc, KDoc, TSDoc.
• Сообщения коммитов, описания PR/MR, ответы на ревью.

Пропускайте: идентификаторы кода, сгенерированные API-справки, цитаты из третьих лиц, названия продуктов, текст лицензии. Уступайте более конкретному руководству, если в репозитории оно уже зафиксировано и существующий текст ему соответствует.

Антипаттерн: «я и так знаю русский, скилл не нужен». Глоссарий, шаблоны жанров, политика канцелярита и длинного тире зафиксированы здесь — общая эрудиция их не заменяет. Если запрос касается русского текста и скилл не подключён, остановитесь и подключите перед ответом.

Что не относится к скиллу и должно остаться у инструментов:

• орфография и политика ё/е (yaspeller, LanguageTool);
• кавычки-«ёлочки», длинное тире, неразрывные пробелы, пробел между числом и единицей измерения (typograf.js);
• продуктовая терминология и сверка с глоссарием (glossary.md);
• проверка placeholders, ICU MessageFormat и Fluent (отдельные скрипты).

Подробности — в разделе 10. Что оставить линтерам.

Когда подгружать модули:

• работаете с UI-строками, формами, пустыми состояниями, ICU-плюралом → modules/ui-strings.md;
• пишете тексты ошибок, валидаций, варнингов и логов → modules/errors-logs.md;
• редактируете комментарии, docstring, PR-описания и ревью → modules/code-comments.md;
• нужен живой материал для калибровки — examples/before-after.md.

2. Базовый стиль

Голос. Вежливо, сдержанно, без формализма. Помогаете читателю выполнить действие, а не отчитываетесь о выполненной работе. Маркетинговые эпитеты («мощный», «бесшовный», «передовой») и эмоциональные восклицания — мимо.

Обращение. Прямое обращение делайте через строчное «вы». Местоимение лучше опускать там, где русский язык и сам обходится: «Откройте файл и сохраните изменения», а не «Вы должны открыть файл, чтобы вы могли сохранить изменения». Не перескакивайте между «вы», «мы» и безличным стилем в одном тексте. «Мы» уместно только для реального командного решения («Мы перешли на gRPC, потому что…»), не для рассказчика-конферансье.

Грамматическое лицо и время. Настоящее время по умолчанию: «Обработчик повторяет запрос три раза», а не «Обработчик будет повторять». Будущее — только когда речь действительно про будущее: «Сборка упадёт, если не задан секрет».

Структура. Сначала ответ или действие, затем подробности. Один абзац — одна мысль. Длина предложения — обычно до 20 слов; всё, что заметно длиннее, требует обоснования. Параллельные пункты в списках начинаются с одной части речи, шаги инструкции — с глагола в повелительном наклонении.

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

Тон по умолчанию. Уверенный без хедж-слов («возможно», «потенциально», «иногда»). Если поведение действительно условное, скажите чем оно обусловлено, а не размывайте формулировку модальностями.

До / после:

• Было: «В данном руководстве будет рассмотрено, каким образом пользователь, возможно, сможет осуществить настройку повторных попыток, которая иногда может оказаться полезной».
• Стало: «Настройте повторы через retry.max_attempts. По умолчанию — три попытки».

3. Жанровые настройки

Разные поверхности — разный регистр. Запомните дефолты:

• Кнопка UI. Глагол в повелительном наклонении, 1–3 слова, без точки: «Сохранить», «Удалить», «Повторить попытку». Подробности — в modules/ui-strings.md.
• Плейсхолдер в поле. Именное словосочетание или короткая подсказка: «Например, prod-eu-1». Полные предложения только если без них непонятно. Точка не нужна.
• Подпись поля. Существительное в именительном падеже: «Имя сервиса», «Порт». Не «Введите имя сервиса» — это инструкция, а не подпись.
• Сообщение об ошибке. Шаблон «Не удалось <действие>» + причина (если известна) + что делать. Подробности — в modules/errors-logs.md.
• Лог разработчика. Технично, компактно, без вежливости. Указывайте идентификаторы, через которые разработчик найдёт строку: trace id, имя сервиса, ключ записи. На «вы» не обращаемся.
• README и обучающий текст. Прямые инструкции, короткие абзацы, единый стиль обращения. Сначала минимальный путь «работает», затем варианты и нюансы.
• API-справка. Нейтральное настоящее время, точные термины, никакой дружелюбной отделки. «Возвращает идентификатор задачи» лучше, чем «Этот метод возвращает вам полезный идентификатор».
• Комментарий в коде. Объясняет почему, инвариант, неочевидную причину, обход бага. Не пересказывает, что делает код. Подробности — в modules/code-comments.md.
• Docstring / Javadoc / KDoc / TSDoc. Первая фраза — короткое описание назначения. Дальше — параметры, возвращаемое значение, ошибки. Идентификаторы кода не переводим и не склоняем.
• Changelog / release notes. Список глагольных пунктов: «Добавили…», «Исправили…», «Убрали…», «Обновили…». Один пункт — одно изменение в терминах того, что меняется для пользователя.
• Сообщение коммита. Сначала тема в повелительном наклонении («исправляет», «добавляет», «удаляет» — в зависимости от принятого стиля проекта), без точки в конце. После пустой строки — тело, объясняющее зачем.
• Описание PR. Зачем, что сделано, как проверить, какие риски. Сначала мотивация: остальное читается в свете причины. Ревьюер должен понять направление, не открывая diff.
• Ответ на ревью. Конкретно и по делу, без сарказма и канцелярских реверансов. Согласие — «Поправил, спасибо». Несогласие — с аргументом и примером.

4. Редактура LLM-черновиков

LLM-черновики на русском узнаются по почерку. Это не список запретов — это список сигналов: один сам по себе ничего не значит, но 3–4 рядом — повод переписать абзац.

Канцелярские шаблоны для рерайта.

• «важно отметить», «следует отметить», «стоит подчеркнуть» → выкиньте обёртку, оставьте мысль. Если мысль того стоит, она держится без анонса.
• «таким образом», «в заключение», «подводя итог» → удалите вместе с обобщающим абзацем, обычно он ничего не добавляет.
• «на сегодняшний день», «в настоящее время», «в современных условиях» → удалите или укажите версию/дату.
• «играет ключевую роль», «является важным», «представляет собой» → замените на глагол: «отвечает за», «обрабатывает», «хранит».
• «является» в роли связки — почти всегда лишнее: «Идентификатор является уникальным» → «Идентификатор уникален».
• «данный», «настоящий», «вышеуказанный» → «этот», «такой», или местоимение вообще не нужно.
• «осуществлять», «производить» в роли служебного глагола: «осуществлять валидацию», «производить запись» → «валидировать», «записывать», «писать».
• «позволяет» в каждом втором предложении → замените прямым глаголом: «logger.WithFields позволяет добавить структурированные поля» → «logger.WithFields добавляет структурированные поля».

Конструкции для разбора.

• Длинные причастные и деепричастные обороты («являющийся», «представляющий собой», «выполняемый сервисом»). Разбейте на два простых предложения. В UI и сообщениях ошибок причастные обороты почти всегда лишние.
• Цепочки родительных падежей («процесс обработки данных запроса пользователя сервиса») — переставьте мысль через действие: «как сервис обрабатывает запросы пользователя».
• Пустые отглагольные существительные («осуществление настройки», «производство запуска», «проведение тестирования») → «настройка», «запуск», «тестирование» (или глагол).
• Механически параллельные тройки («быстрый, надёжный и масштабируемый») — оставьте максимум одно содержательное определение, остальные удалите.
• Чрезмерное длинное тире — см. раздел «Длинное тире» ниже.
• Финальный «обобщающий» абзац, повторяющий введение. Если страница состоит из заголовка, введения и заключения, в которых одна и та же мысль, оставьте только середину.

LLM-почерк помимо канцелярита.

• Симметричные конструкции «не просто X, а Y», «дело не в X, а в Y» — звучат как рекламные слоганы. Сворачивайте до того, что вы реально утверждаете.
• Списки, где каждый пункт начинается с жирного термина и двоеточия. Хорошо для словарей, плохо как способ оформить обычный абзац.
• Хвостовое «-ing»-значение, скалькированное с английского: «...что позволяет командам поставлять ценность в масштабе». Удаляйте такие хвосты до точки.
• Безличные ссылки на авторитет: «общепризнано», «по мнению экспертов», «как известно». Либо ссылка, либо удалить.

Длинное тире

Длинное тире — естественная русская пунктуация, и запрещать его как «AI tell» неправильно. Перебарщивать с ним — тоже неправильно.

Что оставлять:

• тире на месте пропущенной связки: «Идентификатор — строка из 36 символов»;
• тире перед обобщением: «Хранилище, очередь, кэш — всё это вынесли в отдельный сервис»;
• тире для прямой речи и реплик.

Что переписывать:

• абзац, в котором тире — единственное связующее средство и стоит в каждой фразе. Это ритмический штамп LLM.
• два и более длинных тире в одном предложении. Замените одно из них на запятую, скобки или точку.
• тире как универсальный соединитель: «Кэш — хранит — данные — пользователя». Это не пунктуация, это азбука Морзе.

Перед списками и определениями двоеточие обычно естественнее тире.

В коде, CLI-примерах, JSON, YAML, регулярных выражениях и файловых путях тире не меняем никогда: даже если строка стоит внутри Markdown-параграфа, дефис в --quiet — это часть синтаксиса.

5. Канцелярит без догматизма

Главред-стиль и Нора Галь полезны как диагностика, но плохи как догма. Технический текст живёт по другим правилам, чем редакционный.

Что переписываем как канцелярит:

• пустые отглагольные обёртки («осуществление», «проведение», «производство»);
• сцепки «является» / «представляет собой» в роли связки;
• лишние модальные шапки («необходимо отметить, что», «следует помнить, что»);
• длинные цепочки родительных падежей.

Что оставляем как технически точное:

• «сериализация», «инициализация», «аутентификация», «авторизация», «валидация», «миграция», «конфигурация», «оркестрация», «маршрутизация», «персистентность» — это термины. Переводить их на «упрощённый» русский («превращение в строку», «настройка», «проверка») — потеря точности.
• «необходимо», «следует», «должен» — оставляем в нормативных контекстах: спецификации, требования безопасности, совместимость API, инвариант базы данных. В обычной инструкции (README, туториал) лучше прямой императив: «Запустите…», «Добавьте…».
• Пассив и безличные конструкции — допустимы, когда действующее лицо неважно, неизвестно или сам пассив звучит естественнее. «Логи ротируются ежедневно» лучше, чем «Систему ротации логов выполняет планировщик».
• Сложные предложения, когда мысль действительно сложная. Делить её на штрихи ради ритма — портить.

Эвристика: если убрать слово/оборот и текст перестал что-то значить — это не канцелярит, это термин. Если убрать и смысл сохранился — это был шум.

6. Терминология и непереводимые элементы

Что не переводим никогда:

• имена продуктов и их частей: Kubernetes, Helm, Postgres, Kafka, Quarkus, Fiber;
• идентификаторы кода: имена функций, классов, переменных, полей структур;
• флаги и опции CLI: --quiet, -v;
• пути файлов и URL: /etc/foo.yaml, https://example.com;
• имена API, заголовков, переменных окружения: Content-Type, X-Request-Id, KAFKA_BROKERS;
• значения placeholder в форматных строках: {0}, {userName}, %s, ${count}.

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

• В Markdown — обратными кавычками: «Запустите apm install».
• Не склоняйте код: «функция getUser», а не «функция getUserа». Если нужен падеж, добавьте опорное слово: «вызов getUser», «у функции getUser».
• Не оборачивайте код в «ёлочки»: «getUser» — антипаттерн. «Ёлочки» — для цитат и кавычек смысла, не для кода.
• Не подставляйте кодовые токены в роль подлежащего без пояснения: «getUser возвращает null» — норм; «null происходит из-за рассинхронизации» — переформулируйте, добавив существительное.

Что переводим:

• глаголы действия, к которым в русском есть устоявшийся эквивалент: cache → «кэшировать» (или «класть в кэш» в нейтральных контекстах), migrate → «мигрировать»;
• общие технические понятия: request → «запрос», response → «ответ», cluster → «кластер»;
• термины UI: submit → «отправить», cancel → «отменить».

Что переводим осторожно (контекстуально):

• endpoint, payload, feature flag, pull request, merge request — единого устоявшегося перевода нет; выбирайте по контексту и используйте одинаково в одном репозитории.
• topic, partition, broker, consumer, producer — обычно оставляют английский термин в кириллице («топик», «партиция»), потому что русский перевод вызывает больше путаницы.

Стартовый список — в glossary.md. Если в проекте уже есть свой глоссарий — он перевешивает скилл.

Плюрализация и форматирование.

• Русские множественные формы (1, 2–4, 5+) реализуйте через ICU MessageFormat, Fluent или механизм платформы, а не через жёстко зашитые строки в коде.
• Не пишите «1 пользователь(ей)» или «0 файлов(а)» — это всегда ошибка плюрализации.
• Числа и единицы — через неразрывный пробел: «3 ГБ», «10 мс» (см. typograf.js).

7. UI-строки

В UI русский язык не любит англоязычные кальки. «Получите больше из ваших данных» — неестественно; «Извлекайте больше из своих данных» — лучше; «Анализируйте свои данные глубже» — лучше всего, потому что не пытается передать английскую конструкцию буква в букву.

Базовые принципы для UI:

• Кнопки и пункты меню — глагол в повелительном наклонении, без точки.
• Подписи полей — существительные.
• Заголовки экранов, окон, модалок — стиль обычного предложения.
• Тексты-подсказки и tooltips — короткие, без точек, если фраза не предложение.
• Пустые состояния — что произошло и что делать: «Здесь пока ничего нет. Добавьте первое правило, чтобы начать».
• Подтверждения — что произойдёт и предупреждение, если действие необратимо: «Удалить проект? Восстановить его будет нельзя».

Сценарии и шаблоны — в modules/ui-strings.md.

8. Ошибки и логи

Шаблон сообщения об ошибке:

1. Что не получилось (с подлежащим, если оно неочевидно).
2. Почему — если причина известна и полезна.
3. Что делать дальше — конкретное действие или ссылка.

Базовые правила:

• Никаких «упс», «ой», «извините».
• Не «Произошла ошибка при выполнении операции», а «Не удалось сохранить файл report.csv. Проверьте права на запись».
• Не валите всё в одну строку: разделите причину и рекомендацию точкой или переносом.
• Для пользователя — простыми словами; для разработчика — с идентификаторами, через которые можно найти событие в логах.

Логи отличаются от пользовательских ошибок:

• никакого «вы», никакой вежливости;
• технически плотные сообщения с идентификаторами;
• структурные поля (request_id=..., user_id=...) вместо забивания текста контекстом;
• уровень соответствует прозе: INFO — нейтрально, WARN — описывает обходимую ситуацию, ERROR — реальная ошибка, не обходимая.

Подробности и шаблоны — в modules/errors-logs.md.

9. Комментарии в коде и docstrings

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

• Объясняйте почему, какой инвариант, какая совместимость, какой подводный камень. Не пересказывайте сигнатуру.
• Идентификаторы (getUser, MAX_RETRIES) не переводим, не склоняем, не оборачиваем в «ёлочки».
• Не «литературьте» уже точный комментарий. Если фраза «Возвращает идентификатор сессии или nil, если сессия не создана» — точна и коротка, не превращайте её в «Метод используется для того, чтобы получить идентификатор сессии…».
• Docstring: первая фраза — короткое назначение, без подлежащего «Метод/функция». Дальше — параметры, возвращаемое значение, ошибки.
• Публичный API: стабильная терминология, нейтральный тон. Внутренние комментарии могут быть резче, но без сарказма и обзываний на коллег.

Подробности — в modules/code-comments.md.

10. Что оставить линтерам

Скилл сознательно молчит про механические правила, потому что прозой их соблюдать дороже, чем инструментами:

• орфография и опечатки;
• политика ё/е (везде «е», везде «ё», или режим «по словам» — определяется проектом);
• повторы слов в соседних предложениях;
• базовые грамматические согласования;
• кавычки: «ёлочки» снаружи, „лапки“ внутри;
• неразрывные пробелы (между числом и единицей, после однобуквенных предлогов и союзов);
• замена дефиса на длинное тире в нужных контекстах;
• пробел между числом и единицей измерения, форматирование процентов;
• продуктовая терминология (например, всегда «Kafka», а не «кафка»);
• проверка placeholder в форматных строках;
• проверка ICU MessageFormat и Fluent: что все формы плюрала на месте.

Рекомендуемая связка:

• LanguageTool с профилем ru-RU — грамматика, повторы, согласования. Запуск из CI с подавлением правил, шумных на коде. Базовый конфиг — в lint/languagetool.cfg.
• yaspeller — орфография по словарю проекта. Апстрим заархивирован, используйте форк/пин. Базовый конфиг — в lint/.yaspellerrc.json.
• typograf.js — кавычки, тире, неразрывные пробелы. Базовый конфиг — в lint/typograf.config.js.
• Локальный скрипт по глоссарию — превращает glossary.md в правило «эти переводы запрещены / эти обязательны».

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

11. Финальный чеклист

Прогоняйте перед коммитом. Каждый пункт — несколько секунд.

• Сначала ответ или действие? Не «во введении мы рассмотрим», а сразу «Запустите…».
• Длина предложений: всё, что больше 25 слов, оправдано?
• Цепочки родительных и причастные обороты переписаны?
• Длинных тире не больше одного на предложение, не больше пары на абзац?
• Канцелярит вычищен: «является», «данный», «осуществлять», «производить», «играет ключевую роль» — отсутствуют или оправданы?
• Технические нормоформы («сериализация», «валидация», «миграция») сохранены, а не «упрощены»?
• «Необходимо/следует/должен» — только в нормативных контекстах?
• Единое обращение: либо «вы», либо безличное, не вперемешку?
• Идентификаторы и команды — в обратных кавычках, не склонены, не в «ёлочках»?
• Placeholders сохранены ({0}, %s, {userName})?
• Имена продуктов и CLI-флаги не переведены?
• Жанровые форматы соблюдены: коммит, ошибка, changelog, PR?
• Для UI и сообщений ошибок — без «упс», без «к сожалению», без точек на кнопках?

12. Когда нарушать правила

Эти правила существуют, чтобы прозе было лучше читаться. Если в конкретном месте правило ухудшает текст — не применяйте. В частности:

• Пассив корректен, когда исполнитель неизвестен или неинтересен.
• Длинное предложение оправдано, когда мысль действительно длинная и дробление её ломает.
• «Является» уместно в строгих определениях («Хеш — это функция, которая является детерминированной»), хотя обычно лишнее.
• Канцеляризм типа «необходимо» обязателен в спецификациях RFC-стиля и в требованиях безопасности.
• Длинное тире — правильная пунктуация, когда запятая разваливает связь, а скобки прерывают чтение.
• «Мы» уместно для решения команды, «я» — в личном release note или changelog-записи.

Сознательное исключение в пользу читателя — нормально. Привычное «потому что я так пишу» — нет.