В контексте технического руководства мне нужно написать инструкции, проводящие пользователей через несколько стандартных манипуляций. Предоставляя примеры этих манипуляций, я написал короткое предложение, содержащее примеры «до» и «после», которые появляются в (потенциально многострочных) вертикальных блоках. В результате я не уверен, следует ли писать середину предложения с большой буквы. Кроме того, в ELU SE было высказано предположение, что удаление двоеточий перед кодовыми блоками может быть предпочтительнее. Я представил пример этого ниже, а также.
С заглавными буквами
Следовательно, следующий код:
camera.start_recording('foo.h264', quantization=25)
Следует заменить на:
camera.start_recording('foo.h264', quality=25)
Без капитализации
Следовательно, следующий код:
camera.start_recording('foo.h264', quantization=25)
следует заменить на:
camera.start_recording('foo.h264', quality=25)
Без заглавных букв и двоеточий
Следовательно, следующий код
camera.start_recording('foo.h264', quantization=25)
следует заменить на
camera.start_recording('foo.h264', quality=25)
Мой инстинкт подсказывает, что второй или третий примеры предпочтительнее, но мне было бы интересно узнать о каких-либо правилах стиля, касающихся этого. Если на то пошло, если есть лучший способ структурирования таких примеров, который полностью избегает этих проблем, я был бы очень заинтересован!
Должен ли я использовать "или" между примерами? был наиболее подходящим вопросом, который я мог найти для этого (и действительно, это был угол SE, где я впервые задал этот вопрос, прежде чем узнал о Writers), и я склонен согласиться с его рассуждениями о том, что версия в нижнем регистре предпочтительнее. К сожалению, лучшее предложение в его ответе (использовать маркированный список примеров) на самом деле не подходит для потенциально больших блоков кода.
На мой взгляд, любой ответ выглядит сумбурно. Меня раздражает одно «предложение» с заглавными буквами на полпути; то же самое и со строкой, начинающейся без прописной буквы.
Лично я бы реструктурировал все это, чтобы полностью избежать проблемы:
В настоящее время строка 57 файла camera.py выглядит так:
camera.start_recording('foo.h264', quantization=25)В этой строке параметр
quantizationнужно заменить наquality, что даст нам следующее:camera.start_recording('foo.h264', quality=25)
Посмотрите на рисунок 1 ниже. Наш код в настоящее время содержит строку (1); нам нужно заменить его строкой (2).
(1) camera.start_recording('foo.h264', quantization=25) (2) camera.start_recording('foo.h264', quality=25)Рис. 1. Два варианта строки 57 кода в camera.py
(Очевидно, что я не знаю вашего имени файла кода, номеров строк или языка программирования. Замените, где необходимо. «camera.py» можно заменить на пример 1, если вы выбираете этот путь.)
Мне нравится третья версия, без двоеточий, потому что визуальный разрыв и форматирование кода дают понять, что это новый «пункт» или мысль, а фрагмент кода не является грамматически правильным полным предложением. Поскольку вы продолжаете одно предложение через несколько перерывов, я бы не стал использовать заглавные буквы.
Я думаю, что у Watercleave есть еще одно хорошее решение, если вы не можете остановиться на какой-либо комбинации пунктуации и заглавных букв.
Я подхожу к коду в тексте так же, как к диалогу: код — это цитата другого «диктора», поэтому я выделяю его из окружающего текста. Поскольку это не разговорный язык, я не использую соглашения для разговорного языка (тот же шрифт, кавычки и т. д.), чтобы не вызывать путаницы, а использую соглашения для отображения кода (моноширинный шрифт, нумерация строк, блок-кавычки и т. д.). .), но я интегрирую его синтаксически таким же образом, например, используя двоеточие и продолжая предложения строчными буквами.
Поэтому, на мой взгляд, ваш второй пример лучше всего.
Пример:
Когда пятилетняя Мод сказала: «Меня не интересует верховая езда», на самом деле она имела в виду: «Я боюсь лошадей».
Сходным образом:
Следовательно, следующий код:
camera.start_recording('foo.h264', quantization=25), следует заменить на:camera.start_recording('foo.h264', quality=25).
Конечно, вы не должны ставить запятые внутри кавычки кода, поскольку английские правила требуют диалога («езда», «»). Когда вы размещаете фрагменты кода на отдельных строках для лучшей читабельности, синтаксис, заглавные буквы и пунктуация остаются прежними.
Хорошей практикой является напечатать весь сценарий в приложении, а в тексте использовать те же номера строк, что и в этом добавленном сценарии. Затем вы можете ссылаться на код по номерам строк:
В строке 21
quantizationнеобходимо заменить наquality:
21 camera.start_recording('foo.h264', quality=25)
Сделайте самое простое, что работает, в данном случае это пример 3. Правила построения предложений на самом деле не охватывают такие вещи. Это недостаток правил построения предложений, а не самих примеров.
Помните, что первое правило — ясность. Правила грамматики и руководства по стилю существуют для систематизации методов, которые обычно дают наиболее четкий и наименее двусмысленный результат. Они являются хорошим гидом большую часть времени. Но эти правила — слуги ясности, а не ее хозяина, и в некоторых случаях ясность потребует чего-то, что эти правила не могут объяснить.
Делать что-то более запутанное или сложное, чтобы оставаться в стороне от правил грамматики или руководства по стилю, значит ставить лошадь впереди телеги. Как сказал Джордж Оруэлл, «скорее нарушьте любое из этих правил, чем скажите что-нибудь откровенно варварское».
Иногда мне приходится документировать использование кода, и я предпочитаю четкую структуру, поэтому я бы просто сказал:
Следующий код camera.start...
следует заменить на: camera.start_...
Программисты не будут заботиться о вашем выборе грамматики, им нужно будет только знать, какой код использовать. Только мои два цента стоит. Спасибо
Дэйв Джонс
Дэйв Джонс
Водораздел
пользователь