Руководство по набору кода для непрограммистов

13

Фон

Я написал научную статью, содержащую код, и недавно получил доказательства, то есть то, что наборщики журнала создали из моей рукописи. Результат не был приемлемым: отступы противоречивы; в конце каждого блока кода стоит полная остановка; кавычки были уничтожены и т. д. Обратите внимание, что все ошибки не были характерны для языка программирования, который я использовал.

Теперь я понимаю, почему кто-то, у кого нет опыта программирования и нет внешних ресурсов, допустил бы такие ошибки, но во времена Интернета никто не должен быть без внешних ресурсов. Таким образом, я посоветовался с моей любимой поисковой системой, чтобы найти что-то, чтобы предложить, и не нашел ... ничего. Существует множество руководств для программистов о том, как красиво набирать код в LaTeX или аналогичном, что хорошо и правильно, но, очевидно, это не сделано для наборщика, который должен набирать чужой код.

Вопрос

Я ищу ресурс, который:

  • объясняет основы набора текста,
  • предназначен для наборщиков без опыта программирования.
Wrzlprmft
источник
Сложность в том, что это зависит от используемого языка и условных обозначений, поэтому вопрос довольно широкий, даже если ответы просто связывают ресурс
Zach Saucier
2
@ Scott Ну, что касается кавычек, пробелов, символов - действительно, можно обобщить довольно хорошо: они должны быть сохранены.
Михаил V
1
@MikhailV Я просто чувствую, что многие языки кода имеют больше общего с иностранными языками, чем просто руководства. Конечно, вы можете приблизительно определить, где должны быть размещены пробелы и переводы строк, но чтобы быть точным, вам действительно нужно понимать язык, который вы корректируете. Да, вы можете сказать редакторам / корректорам оставить «как есть», но это не значит, что в конечном итоге это будет правильно.
Скотт
1
@Wrzlprmft Забавно, нельзя копировать вставить PDF из Python без потери всех предыдущих пробелов в acrobat или acrobat reader. Это «разумно» удаляет их. Аналогично, если вы вставляете код во многие редакторы WYSIWYG, такие как word или INdesign, они заменят кавычки на кавычки типографов (если вы не отключите такую ​​функцию), но для кода, который действительно ПЛОХО. Также в idesign вы не можете правильно набирать код без введения другого символа для разрыва строки, что может стать плохой вещью, если вы когда-нибудь скопируете код обратно.
joojaa
1
@ usr2564301: Прежде всего, этот вопрос в настоящее время находится в некоторых поисковых системах, и поэтому более вероятно, что любой наборщик, имеющий те же проблемы, что и мой, может найти потенциальный ответ (и если нет, я мог бы быть самодовольным) об этом). Во-вторых, да, я бы включил ссылку в ответ на мои доказательства, потому что это может предотвратить еще не допущенные ошибки во втором раунде доказательств. Также не повредит иметь справочную информацию, если наборщик упрям. Наконец, это журнал / издатель, которому редко приходится иметь дело с кодом, поэтому он несколько отличается от сценариев, которые вы изображаете.
Wrzlprmft

Ответы:

7

Возможно, в действительности смысл в том, что код не должен быть набран так, как люди понимают его. Таким образом, при вставке кода в документ он должен быть дословным , как и во всех пробелах, вкладках, специальных или не специальных символах и без разрывов строк.

  • Вкладки должны быть шириной от 4 до 8 пробелов (наиболее распространенными являются четыре)
  • Шрифт должен быть шрифтом фиксированной ширины. И почти повсеместно имеет быть.
  • Убедитесь, что ваше приложение не делает никаких замен!

    Это означает, что нет лигатур.

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

  • Не позволяйте коду автоматически переходить из одной строки в другую. Не трогайте код, вы не эксперт!

Код не является основным текстом, он не следует типографским соглашениям. Спросите себя, вы бы набрали текст на иллюстрации?

Если вы эксперт

Если вы являетесь экспертом и знаете язык, о котором идет речь, применяется следующее.

Примечание : не угадывайте и не делайте вывод, прочитайте сказанное. Многие языки выглядят одинаково, и код может быть псевдо-языком, который выглядит как реальный код. Тогда ты можешь:

  • Делайте редактор как раскраска / выделение / выделение ключевых слов, если и только если ваша замена имеет одинаковую фиксированную ширину. Лучше пусть редактор сделает это за вас (такие редакторы, как, скажем, scintilla могут экспортировать отформатированный код). Помните, что редактор должен знать язык, может быть, библиотеки тоже.

    Обратите внимание, что если вы делаете это неправильно, это приносит больше вреда, чем пользы.

Если вы являетесь экспертом в области. Как знать язык и библиотеку и понимать соответствующий код:

  • Затем вы можете перестроить код в несколько строк, если он не соответствует вашему макету. Не делайте этого, если вы действительно не знаете, что делаете, вы можете нанести непоправимый вред.

    Лакмусовый тест: не могли бы вы написать соответствующий код? Если нет, то вы не можете судить. Спросите автора.

    Как с этим бороться? Программисты понимают стандарты стиля кода. Просто напишите в инструкции по подаче заявки, что в каждой строке можно разместить не более X символов. Программисты могут сделать это сами. Редакторы кода часто имеют инструменты для этого. Еще одна причина использовать моноширинный шрифт.

Но тогда вы знали все это, в конце концов, вы были экспертом. Лучше пусть автор отредактирует код.

Номера строк?

Некоторые языки программирования и варианты использования могут использовать номера строк. Но будьте осторожны, поскольку в некоторых языках это ошибочное мнение .

Проблемы.

Имейте в виду, что независимо от того, что вы делаете, вы можете столкнуться с невозможными техническими препятствиями. Код на самом деле не должен быть набран, это должен быть просто неформатированный текст. Это приводит к удивительным проблемам.

Например: такие языки, как Python, не могут обрабатываться многими программами просмотра PDF, такими как Adobe Acrobat. Если вы вставите код из файла PDF, редактор решит не включать предыдущий пробел при вставке копии. Это уничтожает возможность вставлять код из PDF в редактор. Там действительно нет хорошего способа справиться с этим!

joojaa
источник
@ usr2564301 ах да так верно
joojaa
1
@ usr2564301 Готово, во всяком случае, я думаю, что читаемый выбор шрифта - это то, что типограф должен понимать. В любом случае, тот, который также различает строчную букву i без точки (да, мы отлаживали один фрагмент кода в течение месяца, потому что мы не знали, что строчная буква «i» отличается от прописной «I» в турецкой локали), образуя 1 тоже
joojaa
«Не позволяйте потоку кода переходить от одной строки к другой» - хороший совет в теории. Но если вы набираете текст для стандартного формата печати 6x9 и у вас есть строка кода с 600 символами, вам будет нелегко прислушаться к ней.
Janus Bahs Jacquet
1
@JanusBahsJacquet Код обычно пишется длиной не более 80 символов в строке. Так что, если вы получите что-то подобное, то, возможно, ваше руководство по подаче документов будет отстойным. Программисты знают о правилах представления, в конце концов, вот что такое кодовые базы. Дело в том, что, разбивая строки, вы можете перестать менять смысл кода.
Джуджаа
1
@JanusBahsJacquet Вот почему вы спрашиваете автора, вы обновляете рекомендации, поэтому вам не нужно делать это слишком часто. в любом случае, если код не может быть разбит на длинные строки, то наборщик не может ничего с этим поделать. Кстати, что бы наборщик сделал для слишком широкой картинки, которую нельзя изменить или обрезать? Во всяком случае, я буду предсказывать, что в будущем будет более распространено предоставление
кода
4

Ответ, конечно, может зависеть от многих факторов, но если мы начнем с правильного, хорошо отформатированного простого текстового кода , то здесь можно более или менее обобщить вещи.

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

Комментарии не являются исполняемой частью кода, поэтому они могут быть переформатированы без особого риска, если вы знаете, действительно ли это комментарий. Итак, первое, на что нужно обратить внимание, это то, как помечаются комментарии.

Полезно знать некоторые основы начального форматирования открытого текста. Например, для Python есть руководство по стилю PEP8 . Хотя это руководство предназначено для Python, его можно использовать как справочник по основным языкам, таким как C / C ++ и Java. Изучение примеров проектов может помочь, если есть сомнения.

Таким образом, первый принцип: не меняйте исходный текст. Я бы прошел контрольный список - убедитесь, что:

  • На любом этапе не происходит автозамена персонажа .
  • Редактирование текста не производится (если только вы не уверены на 100%).
  • Строки не отображаются.
  • Отступы сохраняются визуально и являются последовательными (около четырех х  ширины на уровень отступа).
  • Начальный (нулевой) уровень отступа должен быть видимым.
  • Определенные стили не разрушают форматирование синтаксиса (если используется подсветка синтаксиса).
  • Сделайте резервную копию исходного текста в виде простого текста, чтобы иметь возможность перепроверить исходное форматирование или начать заново.
  • Номера строк, если таковые имеются, должны быть неповрежденными, особенно если на них есть ссылки в пояснениях.

На самом деле, если исходный источник правильно отформатирован, не должно быть переноса строк вообще. Если обернутые линии все еще появляются и их нельзя избежать, то наиболее распространенным решением является одноуровневый висячий отступ (см. Выше связанный PEP). Если разрыв строки необходим - лучше обратитесь к руководству по стилю или к автору.

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

В идеале отступы, которые были сделаны с помощью пробелов или смешанных пробелов и табуляций, должны быть заменены табуляцией (или тем, что программное обеспечение DTP может сделать лучше для вложенных отступов), поэтому, при необходимости, регулировка отступов может быть проще.
Конечно, можно оставлять пробелы, но может быть сложнее управлять их шириной при изменении шрифта и сложнее выравнивать отступы внутренней строки, как в столбцах таблицы.

Моноширинный шрифт + пробелы

Обратите внимание, что если источник отформатирован с пробелами преднамеренно и предназначался для чтения только в моноширинном шрифте (например, ASCII-диаграммы или ASCII-art), следует сохранить пробелы полностью без изменений , но это решение должно быть принято с самого начала. Шрифт "Courier New" является наиболее распространенным для этого случая. Тем не менее, если в этом нет особой необходимости, я советую не использовать моноширинный формат, потому что все меньше и меньше новых людей сегодня выбирают моноширинный код для кодирования, а в случае корректуры пропорциональные шрифты улучшат качество чтения.

Как правило, сжатые (например, узкие шрифты Arial) или более мелкие шрифты могут работать лучше: это делает больший акцент в отличие от основного текста, делает код более компактным и, таким образом, менее вероятно появление нежелательных переносов строк.

Я думаю, что здесь можно нарисовать линию, и если вышеупомянутое сделано, то есть 99% -ная вероятность, что все должно быть хорошо, по крайней мере для простого одноконтрольного кодового блока без цветов.


Инструменты и расширенное форматирование

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

  • цветная печать или просмотр экрана: в полноцветном макете может быть использована любая функция выделения, так что это лучший вариант, но печать может привести к некоторым изменениям цвета.

  • Оттенки серого или ч / б: здесь, конечно, можно использовать жирный шрифт (например, ключевые слова) или курсив (например, комментарии), но обратите внимание, что цвета будут преобразованы в серый со всеми вытекающими последствиями. Например, комментарии, выделенные серым цветом, могут отлично выглядеть на дисплее, но могут стать слишком бледными на бумаге.

Самый важный вопрос заключается в том, есть ли у разработчика макета инструменты, которые могут представлять код в удобочитаемой форме. К счастью, существует множество бесплатных инструментов для редактирования кода, наиболее заметными (для Windows) являются: Notepad ++, VSCode, Visual Studio . Но следует помнить о возможных неявных автоматических преобразованиях табуляции в пробелы.

В Notepad ++ есть возможность экспортировать код в формате RTF , который сохранит все форматирование и подсветку синтаксиса источника.

Если макет не требует изменения потока текста в представлении кода, можно напрямую использовать изображения (снимки экрана) - он не так гибок, как текст, но сохранит 100% форматирование и нумерацию строк и может сэкономить много времени. Например, номера строк сложно сохранить в текстовом виде. Также экспорт в PDF является хорошей альтернативой - но не все программное обеспечение DTP может встраивать PDF-файлы, и при печати в PDF может быть потеряно некоторое форматирование.

Например, мои настройки для кода Python в Notepad ++ выглядят так:
введите описание изображения здесь

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

Цветовая схема, конечно, индивидуальна, определена в конфигураторе стилей редактора, который уже знает о поддерживаемом языке, что затрудняет ложное форматирование, даже если кто-то не знает синтаксис. Здесь должны работать общие правила типографики: не слишком много цветов, согласованные шрифты, отступы, удобный межстрочный интервал.

Дополнительные инструменты / плагины для пользовательских определений языка также распространены, но они требуют знания синтаксиса.

Михаил V
источник
Это прекрасный и тщательно продуманный ответ. Но скриншоты могут быть неоптимальными, если вы планируете их напечатать из-за разрешения. Что-то иметь в виду.
Джереми Карлсон
1
@JeremyCarlson в Np ++, размер шрифта / межстрочный интервал также можно регулировать - так что теоретически нет ограничений для разрешения скриншота, но его будет сложнее создать, особенно на маленьком дисплее. Может быть даже какая-то хитрость, чтобы использовать виртуальный дисплей и установить очень большой размер окна
Михаил V
потому что все меньше и меньше новых людей сегодня выбирают моноширинное пространство для кодирования - это может быть, но моноширинное пространство все еще используется подавляющим большинством. Вы не можете просто перевести обычные правила набора текста в код. Например, знаки препинания важнее, чем в обычных текстах (большинство аргументов из этого моего ответа переводят на это). Шрифт немонокального кода будет значительно отличаться от шрифта обычного текста. Кроме того, вы часто хотите, чтобы некоторые подобные структуры были выровнены по горизонтали, например, a[i][j] = 1a[m][n] = 2.
Wrzlprmft
@Wrzlprmft спасибо за изменения. И да, не так много хороших шрифтов, оптимизированных для кода и математики (с Верданой все в порядке). Действительно, у «Таймс» есть крошечный период, двоеточие и некоторые другие проблемы, но я использую его все время - «выгоды перевешивают затраты»
Михаил V
-5

В HTML есть набор тегов <code> ... </ code>, который говорит читателю / интерпретатору обрабатывать содержимое буквально. Кроме того, <pre> ... </ pre> делает то же самое. Как человек, которому часто приходилось набирать формулы, уравнения и код для публикации, я также выступаю за использование ИЗОБРАЖЕНИЙ для этого ... создайте .gif, .jpg или .png проблемного элемента.

Другим фактором является то, что код традиционно отображается в моноширинном Courier или другом моноширинном шрифте, потому что он семафор или телеграфирует читателю, что это не основной текст. Я подписываюсь на этот стиль выбора, я думаю, что это имеет большой смысл.

В большинстве "унаследованных" систем набора текста математические уравнения достаточно высокой сложности были чрезвычайно трудоемкими ... и чреваты ошибками.

dwoz
источник
конечно, изображения не обрезать и вставлять!
dwoz
3
Я не понимаю, как это отвечает на вопрос, который задают вообще
Зак Сауцер