язык уехал в 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
@@ -3127,3 +3127,43 @@ JJJ): у профиля обязан быть один правильный от
|
||||
точно говорит, могла ли измениться дорогая величина. Так дорогая проверка
|
||||
остаётся редкой и при этом не забытой.
|
||||
|
||||
|
||||
## 49. Дом общего правила вышел из плагина (2026-08-09)
|
||||
|
||||
**АЕАКА. Язык уехал в `shared/`, потому что общее правило не может принадлежать
|
||||
половине.** Дом языка лежал в `av-dev-pm/skills/canon/references/language.md` —
|
||||
внутри одного скилла одного плагина. Пока плагин был один, это читалось как «дом
|
||||
рядом с главным потребителем». Разделение на самодостаточные `docs` и `tasks`
|
||||
превращает то же место в утверждение, что язык принадлежит канону: плагин задач,
|
||||
поставленный без канона, потерял бы правила письма вместе с ним. Дом переехал в
|
||||
`shared/` и не принадлежит ни одному плагину, а плагины везут дословные копии.
|
||||
Самодостаточность держится **копией, а не ссылкой**: `shared/` нужен этому
|
||||
репозиторию, а не установленному плагину.
|
||||
|
||||
**АЕАКБ. Устав вычитки стал копией целиком, а не четырьмя таблицами из десяти.**
|
||||
`doc-wording` копировал из дома англицизмы, словарь, жаргон и порог правки —
|
||||
четыре блока; девять правил он излагал своими словами, и эти слова с домом никто
|
||||
не сверял. Там дрейф и копился молча: в доме правило «одна мысль — одно
|
||||
предложение» требовало выносить придаточное, в уставе — не резать причинную
|
||||
связь, и каждая версия выглядела полной. Теперь блок один, `язык-правила`, и
|
||||
берётся он целиком. Условие переезда: текст правил написан безлично, а всё,
|
||||
обращённое к проходу («пиши так-то», «про это молчи»), вынесено из блока в свой
|
||||
раздел устава. **Правило принадлежит дому, способ доложить о нём — уставу.**
|
||||
|
||||
**АЕАКВ. `порог-правки` остался отдельным блоком, и это следствие разметки, а не
|
||||
вкуса.** Его берёт `task-form`, который правил языка не проверяет вовсе.
|
||||
Вложенных блоков `copies.py` не знает — лежи порог внутри `язык-правила`, забрать
|
||||
его отдельно было бы нечем, и `task-form` вёз бы весь устав чужого прохода.
|
||||
Разрез домов идёт **по потребителю, а не по теме**: три блока вместо одного
|
||||
стоят двух лишних маркеров и снимают ложную зависимость.
|
||||
|
||||
### Что из этого следует
|
||||
|
||||
171. **Общее правило не хранится внутри одного из тех, кто им пользуется.** Пока
|
||||
пользователь один, дом рядом с ним выглядит удобством; со вторым
|
||||
пользователем то же место начинает утверждать, что правило принадлежит
|
||||
первому.
|
||||
172. **Пересказ своими словами — это копия, которую никто не сверяет.** Блок,
|
||||
взятый целиком, читается дороже, но расхождение в нём ловит машина;
|
||||
сокращённое изложение экономит строки и платит молчаливым дрейфом.
|
||||
|
||||
|
||||
@@ -236,6 +236,7 @@ claude plugin uninstall <плагин>@av-dev-skills --scope project
|
||||
<plugin>/skills/<skill>/references/ что читается по ссылке из скилла
|
||||
<plugin>/skills/<skill>/scripts/ tasks.py, docs.py
|
||||
<plugin>/agents/ charter'ы сабагентов
|
||||
shared/ дома правил, общих для нескольких плагинов
|
||||
scripts/ проверки репозитория: копии, диаграммы, фронтматтеры
|
||||
pyproject.toml линтеры скриптов, только для этого репозитория
|
||||
lefthook.yml гейт коммита: проверки документов
|
||||
@@ -311,6 +312,13 @@ uv run python scripts/copies.py # 0 сошлось, 1 расхождение
|
||||
сверку не входят. Маркер, уехавший в проект вместе со скелетом, там полезен: он
|
||||
говорит, что у текста есть дом и правится он там.
|
||||
|
||||
**Дом правила, общего для нескольких плагинов, лежит в `shared/` и ни одному из
|
||||
них не принадлежит.** Так живёт язык проектных текстов: он одинаково нужен
|
||||
документам канона и задачам, и хранить его внутри одного плагина значило бы
|
||||
отдать общее правило во владение половине. Плагин везёт копию и потому остаётся
|
||||
самодостаточным — `shared/` нужен этому репозиторию, а не установленному
|
||||
плагину.
|
||||
|
||||
Скрипт ловит четыре вещи: копия разошлась с домом (с диффом), копия указывает не
|
||||
на тот файл, дом остался без копий, разметка сломана. Чего он **не** ловит —
|
||||
копию, которую забыли пометить: помечать — по-прежнему решение человека.
|
||||
|
||||
@@ -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,20 +64,18 @@ color: green
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогай.
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращай, но не дели. То же с любым полем вида `- **Имя:** …`.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
<!-- копия: язык-англицизмы из av-dev-pm/skills/canon/references/language.md -->
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
@@ -87,19 +89,18 @@ color: green
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий и
|
||||
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
|
||||
таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
<!-- /копия: язык-англицизмы -->
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
6. **Слово из своего словаря не трогается — список закрыт.**
|
||||
|
||||
<!-- копия: язык-словарь из av-dev-pm/skills/canon/references/language.md -->
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
@@ -112,22 +113,19 @@ color: green
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а
|
||||
не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует
|
||||
ввода одной строкой при первом употреблении.
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо:
|
||||
**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то),
|
||||
**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд**
|
||||
(руководство). Каждое было латинизмом или калькой при живом русском слове, и
|
||||
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
|
||||
словарём, не будучи им.
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
|
||||
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
|
||||
есть выглядело словарём, не будучи им.
|
||||
|
||||
<!-- /копия: язык-словарь -->
|
||||
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.**
|
||||
|
||||
<!-- копия: язык-жаргон из av-dev-pm/skills/canon/references/language.md -->
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
@@ -137,29 +135,39 @@ color: green
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
|
||||
описанием того, что происходит.**
|
||||
|
||||
<!-- /копия: язык-жаргон -->
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
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,11 +66,48 @@
|
||||
значит называть состояние и остаток, а не пересказывать, как было интересно
|
||||
разбираться.
|
||||
|
||||
## Англицизмы
|
||||
<!-- /копия: язык-доктрина -->
|
||||
|
||||
Англицизм-калька заменяется, когда у него есть естественный русский аналог.
|
||||
## Правила
|
||||
|
||||
<!-- дом: язык-англицизмы -->
|
||||
<!-- копия: язык-правила из shared/language.md -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
@@ -114,23 +122,18 @@
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий и
|
||||
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
|
||||
таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
<!-- /дом: язык-англицизмы -->
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
## Свой словарь — закрытый список
|
||||
|
||||
Слово, не переводимое потому, что оно **имя вещи этого процесса**, а не украшение.
|
||||
Оговорка «термин прижился» без списка проверяема на глаз и потому не проверяема:
|
||||
прижившимся выглядит любое слово, встреченное трижды.
|
||||
|
||||
<!-- дом: язык-словарь -->
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
@@ -143,25 +146,19 @@
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а
|
||||
не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует
|
||||
ввода одной строкой при первом употреблении.
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо:
|
||||
**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то),
|
||||
**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд**
|
||||
(руководство). Каждое было латинизмом или калькой при живом русском слове, и
|
||||
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
|
||||
словарём, не будучи им.
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
|
||||
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
|
||||
есть выглядело словарём, не будучи им.
|
||||
|
||||
<!-- /дом: язык-словарь -->
|
||||
|
||||
## Жаргон и метафоры
|
||||
|
||||
Система не описывается внутренними метафорами и образными ярлыками: автору они
|
||||
понятны, читателю — нет. Вещь называется прямо.
|
||||
|
||||
<!-- дом: язык-жаргон -->
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
@@ -171,24 +168,30 @@
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
|
||||
описанием того, что происходит.**
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
<!-- /дом: язык-жаргон -->
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
## Термин, которого нет в проекте
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях,
|
||||
**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи
|
||||
— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему
|
||||
через квартал.
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже
|
||||
непонятного слова, потому что выглядит понятной.
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
## Порог правки
|
||||
|
||||
<!-- дом: порог-правки -->
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
@@ -202,7 +205,7 @@
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /дом: порог-правки -->
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
||||
Беклог не переписывают ради языка.
|
||||
|
||||
@@ -0,0 +1,226 @@
|
||||
# Язык проектных текстов
|
||||
|
||||
**Это дом.** Файл не входит ни в один плагин: язык общий для документов канона и
|
||||
для задач, и хранить его внутри одного из них значило бы отдать общее правило во
|
||||
владение половине. Плагины везут **копии**, помеченные разметкой `copies.py`, и
|
||||
расхождение ловит гейт коммита, а не внимание.
|
||||
|
||||
Правится **здесь**. Копия, поправленная у себя, — расхождение, а не правка.
|
||||
|
||||
Три блока, и делятся они по потребителю, а не по теме:
|
||||
|
||||
| Блок | Что в нём | Кто копирует |
|
||||
| --- | --- | --- |
|
||||
| `язык-доктрина` | зачем стиль нужен, что взято сверх устава, что отброшено | справочник языка в плагине |
|
||||
| `язык-правила` | девять правил, по которым судят текст | справочник и уставы вычитки |
|
||||
| `порог-правки` | когда находка не заводится | справочник, уставы вычитки, `task-form` |
|
||||
|
||||
`порог-правки` вынесен из правил намеренно: он нужен и тому, кто правил языка не
|
||||
проверяет вовсе, — а вложенных блоков разметка не знает, и внутри `язык-правила`
|
||||
его было бы не забрать отдельно.
|
||||
|
||||
<!-- дом: язык-доктрина -->
|
||||
|
||||
Правила — для всего, что пишется словами: задачи и цели, документы канона,
|
||||
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
|
||||
сообщений программы пользователю — там свои конвенции проекта.
|
||||
|
||||
Основа — **информационный стиль** Максима Ильяхова ([учебник
|
||||
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
|
||||
написан для рекламы, статей и писем, поэтому взят не целиком.
|
||||
|
||||
## Зачем он здесь
|
||||
|
||||
Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
|
||||
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
|
||||
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
|
||||
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
|
||||
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
|
||||
а это и есть цена, которой мы избегаем.
|
||||
|
||||
## Что взято сверх правил вычитки
|
||||
|
||||
Эти три требования судит человек, а не проход вычитки: находка по ним требует
|
||||
увидеть текст целиком, а не фразу.
|
||||
|
||||
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
|
||||
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
|
||||
«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
|
||||
собственный вопрос («что это за система», «как сложено», «почему так решили»).
|
||||
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
|
||||
исход правки.
|
||||
|
||||
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
|
||||
грамматической формой, разделы одного вида — одним порядком, заголовки одного
|
||||
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
|
||||
ищет её.
|
||||
|
||||
**Заголовок работает.** Заголовок называет содержание раздела, а не тему
|
||||
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
|
||||
столько, чтобы длинный текст можно было просматривать, а не только читать
|
||||
подряд.
|
||||
|
||||
## Что отброшено намеренно
|
||||
|
||||
Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
|
||||
читают потому, что надо, и держать его нечем. Отсюда три расхождения:
|
||||
|
||||
- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
|
||||
ломает причинную связь, а в решении и в задаче ценность именно в ней:
|
||||
«поэтому», «иначе», «раз так» несут смысл и остаются.
|
||||
- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
|
||||
«в отличие от» — это условия и противопоставления, то есть сведения. Режутся
|
||||
вводные, которые не меняют смысл предложения.
|
||||
- **Скобки и точка с запятой остаются.** В технической записи скобки несут
|
||||
уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
|
||||
не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
|
||||
«дописать позже», и такой текст лучше не публиковать.
|
||||
|
||||
И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
|
||||
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
|
||||
значит называть состояние и остаток, а не пересказывать, как было интересно
|
||||
разбираться.
|
||||
|
||||
<!-- /дом: язык-доктрина -->
|
||||
|
||||
## Правила
|
||||
|
||||
<!-- дом: язык-правила -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
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`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
<!-- /дом: язык-правила -->
|
||||
|
||||
## Порог правки
|
||||
|
||||
<!-- дом: порог-правки -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
||||
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
||||
|
||||
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
||||
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
||||
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
||||
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /дом: порог-правки -->
|
||||
|
||||
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
||||
Беклог не переписывают ради языка.
|
||||
Reference in New Issue
Block a user