Пунктуация в IT-текстах и документации
Технический текст живет по своим законам. Здесь сталкиваются строгие правила русского языка и требования синтаксиса языков программирования. Разбираемся, как не превратить README в кашу и где ставить запятые в Jira-тикетах.
Основные правила технического письма
1. Кавычки: «ёлочки» vs "лапки"
В русском языке основным стандартом являются «кавычки-ёлочки». Однако в IT-контексте, когда мы цитируем код, названия переменных или строк в JSON, допустимо и даже желательно использовать прямые "программистские" кавычки, чтобы не вводить пользователя в заблуждение.
"production".save_user().2. Запятые в перечислении параметров
Когда вы описываете аргументы функции или ключи API в тексте предложения, они подчиняются правилам однородных членов. Если перечисление длинное или содержит сложную структуру, лучше выносить его в маркированный список.
id, token, payload и необязательный флаг debug.
3. Англицизмы и сленг
Такие слова, как «деплой», «мерж», «коммит», в русском языке часто выступают как обычные существительные или глаголы. Они не требуют кавычек, если прочно вошли в профессиональный обиход. Но помните: избыток сленга делает текст нечитаемым для внешних стейкхолдеров.
«Пунктуация — это те же нотные знаки. Она твердо держит текст и не дает ему рассыпаться.»
Примеры в документации
«Система должна валидировать email, пароль и номер телефона пользователя при регистрации».
Разбор: Перечисление однородных дополнений (что именно валидировать) требует запятых.
«Данные, полученные из кэша, могут быть неактуальными».
Разбор: Классический причастный оборот после определяемого слова. Обособляется запятыми.
«Если вы используете Docker, запустите контейнер командой docker-compose up».
Разбор: Сложноподчиненное предложение с союзом «если». Перед главной частью ставится запятая.
Хаб «Союзы»
Соединительные, противительные и разделительные союзы — основа пунктуации в сложном предложении. Изучите правила для других союзов: