язык уехал в shared: дом вне плагинов, устав вычитки — копия целиком
Дом языка лежал в av-dev-pm/skills/canon/references/language.md — внутри одного скилла одного плагина. Пока плагин был один, это читалось как «дом рядом с главным потребителем». Разделение на самодостаточные docs и tasks превращает то же место в утверждение, что язык принадлежит канону: плагин задач, поставленный без канона, потерял бы правила письма вместе с ним. Дом переехал в shared/ и не принадлежит ни одному плагину, плагины везут дословные копии. Самодостаточность держится копией, а не ссылкой: shared/ нужен этому репозиторию, а не установленному плагину. Устав вычитки стал копией целиком. doc-wording копировал из дома англицизмы, словарь, жаргон и порог правки — четыре блока; девять правил он излагал своими словами, и эти слова с домом никто не сверял. Там дрейф и копился молча: в доме правило «одна мысль — одно предложение» требовало выносить придаточное, в уставе — не резать причинную связь, и каждая версия выглядела полной. Из десяти правил машина сверяла четыре, теперь сверяет все. Условие переезда: текст правил написан безлично, а всё, обращённое к проходу («пиши так-то», «про это молчи»), вынесено из блока в раздел «Что из этих правил докладывается особым образом». Правило принадлежит дому, способ доложить о нём — уставу. Блоков три, и делятся они по потребителю, а не по теме: язык-доктрина (зачем стиль, полезное действие, параллельность, заголовок, что отброшено), язык-правила (девять правил с тремя таблицами), порог-правки. Порог оставлен отдельным потому, что его берёт task-form, который правил языка не проверяет вовсе; вложенных блоков copies.py не знает, и внутри язык-правила забрать порог было бы нечем. Потребители собраны из дома скриптом, а не руками. Домов 6 вместо 7 — три таблицы слились в язык-правила; копий 9 вместо 8. Гейт зелёный: копии, фронтматтеры, диаграммы. Решение — 49. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -25,7 +25,7 @@ color: green
|
||||
|
||||
Список файлов или каталог: документы канона (`docs/*.md`), решения в
|
||||
`docs/adr/`, записки в `docs/research/`, записи каталога задач
|
||||
(`docs/tasks/items/<slug>.md`) — вперемешку тоже.
|
||||
(`items/<slug>.md`) — вперемешку тоже.
|
||||
|
||||
Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура,
|
||||
конвенции: по ним проверяется, известен ли термин. **Не назвали — считай
|
||||
@@ -34,9 +34,13 @@ color: green
|
||||
|
||||
## Правила
|
||||
|
||||
Дом — `av-dev-pm/skills/canon/references/language.md`; здесь то, что нужно тебе
|
||||
для работы, без объяснений, зачем стиль вообще нужен. У каждого правила названа
|
||||
причина: она же говорит, где правило **не** применяется.
|
||||
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
|
||||
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
|
||||
|
||||
<!-- копия: язык-правила из shared/language.md -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
@@ -60,106 +64,110 @@ color: green
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогай.
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращай, но не дели. То же с любым полем вида `- **Имя:** …`.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
<!-- копия: язык-англицизмы из av-dev-pm/skills/canon/references/language.md -->
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий и
|
||||
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
|
||||
таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
<!-- /копия: язык-англицизмы -->
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
|
||||
6. **Слово из своего словаря не трогается — список закрыт.**
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
<!-- копия: язык-словарь из av-dev-pm/skills/canon/references/language.md -->
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
|
||||
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
|
||||
есть выглядело словарём, не будучи им.
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а
|
||||
не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует
|
||||
ввода одной строкой при первом употреблении.
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо:
|
||||
**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то),
|
||||
**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд**
|
||||
(руководство). Каждое было латинизмом или калькой при живом русском слове, и
|
||||
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
|
||||
словарём, не будучи им.
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
<!-- /копия: язык-словарь -->
|
||||
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.**
|
||||
|
||||
<!-- копия: язык-жаргон из av-dev-pm/skills/canon/references/language.md -->
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
|
||||
описанием того, что происходит.**
|
||||
|
||||
<!-- /копия: язык-жаргон -->
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную
|
||||
область. Пиши «термин «X» не встречается ни в документах, ни в других
|
||||
поданных файлах — введи строкой или назови известным словом».
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
**Слово, занятое в другом смысле, — та же находка.** Термин, который в одном
|
||||
документе проекта значит одно, а здесь другое, ломает оба; назови оба места.
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками.
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
Кириллицу в имени и не-kebab-case ловят `docs.py` и `tasks.py` — про них
|
||||
молчи. Твоё — **транслит**, потому что машина проверяет его эвристикой и
|
||||
ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — готовое
|
||||
английское имя на замену плюс напоминание, что переименование это **перенос
|
||||
ссылок одним проходом**, а не правка одного файла.
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
### Что из этих правил докладывается особым образом
|
||||
|
||||
**Правило 8, неизвестный термин.** Своей догадки не подставляй — ты не знаешь
|
||||
предметную область. Пиши «термин «X» не встречается ни в документах, ни в других
|
||||
поданных файлах — введи строкой или назови известным словом». Слово, занятое в
|
||||
другом смысле, — та же находка, и в ней **называются оба места**.
|
||||
|
||||
**Правило 9, имя файла.** Кириллицу в имени и не-kebab-case ловят `docs.py` и
|
||||
`tasks.py` — про них молчи. Твоё — **транслит**, потому что машина проверяет его
|
||||
эвристикой и ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка —
|
||||
готовое английское имя на замену плюс напоминание про перенос ссылок одним
|
||||
проходом.
|
||||
|
||||
## Чего ты не проверяешь
|
||||
|
||||
@@ -181,9 +189,13 @@ color: green
|
||||
**Содержание**: верно ли решение, нужна ли задача, полна ли архитектура. Это
|
||||
разбор, а не вычитка, — и о нём тоже молчи.
|
||||
|
||||
**Полезное действие, параллельность и работающий заголовок** — тоже не твои.
|
||||
Они в доктрине языка, судит их человек: находка по ним требует увидеть текст
|
||||
целиком, а не фразу.
|
||||
|
||||
## Порог вмешательства
|
||||
|
||||
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
|
||||
@@ -143,7 +143,7 @@ color: green
|
||||
|
||||
## Порог вмешательства
|
||||
|
||||
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
|
||||
@@ -1,13 +1,18 @@
|
||||
# Язык проектных текстов
|
||||
|
||||
Правила для всего, что пишется словами: задачи и цели, документы канона,
|
||||
**Копия.** Дом — `shared/language.md` в репозитории плагинов; язык общий для
|
||||
документов канона и для задач, и потому не принадлежит ни одному плагину.
|
||||
Правится дом, а не этот файл: расхождение ловит `copies.py` на гейте коммита.
|
||||
|
||||
<!-- копия: язык-доктрина из shared/language.md -->
|
||||
|
||||
Правила — для всего, что пишется словами: задачи и цели, документы канона,
|
||||
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
|
||||
сообщений программы пользователю — там свои конвенции проекта.
|
||||
|
||||
Основа — **информационный стиль** Максима Ильяхова ([учебник
|
||||
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
|
||||
написан для рекламы, статей и писем, поэтому взят не целиком: ниже сказано, что
|
||||
взято и что отброшено намеренно.
|
||||
написан для рекламы, статей и писем, поэтому взят не целиком.
|
||||
|
||||
## Зачем он здесь
|
||||
|
||||
@@ -18,7 +23,10 @@
|
||||
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
|
||||
а это и есть цена, которой мы избегаем.
|
||||
|
||||
## Что взято
|
||||
## Что взято сверх правил вычитки
|
||||
|
||||
Эти три требования судит человек, а не проход вычитки: находка по ним требует
|
||||
увидеть текст целиком, а не фразу.
|
||||
|
||||
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
|
||||
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
|
||||
@@ -27,43 +35,6 @@
|
||||
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
|
||||
исход правки.
|
||||
|
||||
**Глагол вместо отглагольного существительного, действие вместо состояния.**
|
||||
«Обработчик не проверяет владельца», а не «проверка владельца не
|
||||
осуществляется»; «сопоставляет по имени», а не «осуществляет сопоставление по
|
||||
имени». Отглагольное существительное прячет того, кто действует, — а в
|
||||
техническом тексте именно он и важен.
|
||||
|
||||
**Активный залог.** «Скрипт переписывает индекс», а не «индекс переписывается
|
||||
скриптом». Страдательный залог остаётся там, где деятель неизвестен или
|
||||
неважен, и это не поблажка: «файл удаляется» верно, когда удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
**Конкретика вместо оценок.** Факты, имена, цифры: «время ответа доходит до
|
||||
800 мс», а не «работает медленно»; «тело 40 МиБ держит блокировку 5 секунд», а
|
||||
не «большие тела тормозят». Оценка допустима, когда за ней в той же фразе стоит
|
||||
факт. Без факта оценка — не сведение, а настроение.
|
||||
|
||||
**Стоп-слова.** Убирается то, что можно убрать без потери смысла:
|
||||
|
||||
| Что | Примеры |
|
||||
| --- | --- |
|
||||
| канцелярит | является, осуществляется, в целях, в рамках, данный, вышеуказанный, необходимо отметить |
|
||||
| вводные-паразиты | в общем, как известно, стоит отметить, не секрет, что |
|
||||
| усилители | очень, крайне, достаточно, абсолютно, максимально, полностью |
|
||||
| синонимы одного качества | «понятный и простой», «быстрый и производительный» |
|
||||
| неопределённое | какой-то, некоторый, соответствующий, определённый |
|
||||
|
||||
Проверка одна: **вычеркни слово. Смысл изменился — оставляй.**
|
||||
|
||||
**Одна мысль — одно предложение.** Предложение, в котором два независимых
|
||||
утверждения, делится. Придаточное, которое можно вынести в отдельную фразу,
|
||||
выносится.
|
||||
|
||||
Исключение — **поля, которым формат отвёл одно предложение**. «Зачем» в мете
|
||||
задачи именно такое: оно повторяется строкой индекса, и второе предложение там
|
||||
просто не поместится. Такое поле либо укладывается в одну фразу, либо
|
||||
сокращается, но не делится.
|
||||
|
||||
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
|
||||
грамматической формой, разделы одного вида — одним порядком, заголовки одного
|
||||
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
|
||||
@@ -95,100 +66,132 @@
|
||||
значит называть состояние и остаток, а не пересказывать, как было интересно
|
||||
разбираться.
|
||||
|
||||
## Англицизмы
|
||||
<!-- /копия: язык-доктрина -->
|
||||
|
||||
Англицизм-калька заменяется, когда у него есть естественный русский аналог.
|
||||
## Правила
|
||||
|
||||
<!-- дом: язык-англицизмы -->
|
||||
<!-- копия: язык-правила из shared/language.md -->
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий и
|
||||
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
|
||||
таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
<!-- /дом: язык-англицизмы -->
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
## Свой словарь — закрытый список
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
Слово, не переводимое потому, что оно **имя вещи этого процесса**, а не украшение.
|
||||
Оговорка «термин прижился» без списка проверяема на глаз и потому не проверяема:
|
||||
прижившимся выглядит любое слово, встреченное трижды.
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
<!-- дом: язык-словарь -->
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а
|
||||
не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует
|
||||
ввода одной строкой при первом употреблении.
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо:
|
||||
**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то),
|
||||
**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд**
|
||||
(руководство). Каждое было латинизмом или калькой при живом русском слове, и
|
||||
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
|
||||
словарём, не будучи им.
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
<!-- /дом: язык-словарь -->
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
## Жаргон и метафоры
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
Система не описывается внутренними метафорами и образными ярлыками: автору они
|
||||
понятны, читателю — нет. Вещь называется прямо.
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
<!-- дом: язык-жаргон -->
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
|
||||
описанием того, что происходит.**
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
|
||||
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
|
||||
есть выглядело словарём, не будучи им.
|
||||
|
||||
<!-- /дом: язык-жаргон -->
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
## Термин, которого нет в проекте
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях,
|
||||
**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи
|
||||
— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему
|
||||
через квартал.
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже
|
||||
непонятного слова, потому что выглядит понятной.
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
## Порог правки
|
||||
|
||||
<!-- дом: порог-правки -->
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
@@ -202,7 +205,7 @@
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /дом: порог-правки -->
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
||||
Беклог не переписывают ради языка.
|
||||
|
||||
Reference in New Issue
Block a user