非程序员排版代码指南

背景

我撰写了一篇包含代码的科学论文，最近收到了证明，即该期刊的排字员根据我的手稿创建的内容。结果不可接受：缩进不一致；每个代码块的末尾都有一个句号；引号已被破坏，等等。请注意所有错误不是特定于我使用的编程语言。

现在，我明白了为什么没有编程经验，没有外部资源的人会犯这样的错误，但是在Internet时代，没有人应该没有外部资源。因此，我咨询了我最喜欢的搜索引擎，以寻找可以建议的东西，但发现……什么都没有。程序员有很多指南如何在LaTeX或类似版本中精美地排版代码，这都是不错的选择，但是显然，这不适用于必须排版他人代码的排版人员。

题

我正在寻找一种资源：

• 解释排版代码的基础，
• 是针对没有编程经验的排字工人。

也许真正的重点是，不应真正按照人们理解排版的方式来排版代码。因此，在将代码放入文档中时，应原样放置在该文档中，因为所有空格，制表符，特殊或非特殊字符以及换行符均应完整保留。

• 制表符的宽度应为4或8（最常见的是四个）
• 字体应为固定宽度的字体。而且几乎必须如此。

• 确保您的应用程序不做任何替换！

  那意味着没有连字。

  同样，许多程序（例如Word和InDesign）应用程序都将对印刷者的直引号更改。在将代码放入文档之前，请确保禁用这些选项。

• 不要让代码自动从一行流到另一行。请勿触摸密码，您不是专家！

代码不是正文，它不遵循任何印刷约定。问问自己，您会在插图中排版文本吗？

如果你是专家

如果您是专家，并且知道所使用的语言，则以下内容适用。

注意：不要猜测或推断，请阅读所讲内容。许多语言看起来都一样，并且代码可能是某些伪代码，看起来像真实代码。那么你就可以：

• 当且仅当替换具有相同的固定宽度时，编辑器才会喜欢对关键字进行上色/粗体显示/斜体显示。最好让编辑器为您执行此操作（例如scintilla之类的编辑器可以导出格式化的代码）。请记住，编辑者需要了解语言，也许还需要了解库。

  请注意，如果您做错了此事，则弊大于利。

如果您是领域专家。如所知语言和库并了解所涉及的代码：

• 然后，如果不适合您的布局，则可以将代码重新对齐为几行。除非您真的知道自己在做什么，否则不要这样做，否则可能会造成无法弥补的伤害。

  石蕊测试是您是否编写了有问题的代码。如果没有，那么您将无法判断。询问作者。

  该如何处理？程序员了解代码风格标准。只需在提交准则中写明，每行只能容纳X个字符。程序员然后可以自己执行此操作。代码编辑器经常为此提供工具。使用等宽字体的另一个原因。

但是后来您知道了所有这一切，毕竟您是专家。最好让作者编辑代码。

行号？

某些编程语言和用例可能会受益于行号。不过请小心，因为这在某些语言中是虚假的。

问题。

请注意，无论您做什么，实际上都可能遇到不可能的技术障碍。不应真正排版代码，而应仅是未格式化的文本。这导致了令人惊讶的问题。

例如：诸如Python之类的语言无法由Adobe Acrobat之类的许多PDF查看器处理。如果将代码粘贴到PDF文件之外，则编辑器会在复制粘贴时决定不包括前面的空格。这破坏了将代码从PDF粘贴到编辑器的能力。确实没有解决这个问题的好方法！

答案当然可能取决于许多因素，但是如果我们从正确的，格式正确的纯文本代码开始，那么这里可以或多或少地概括一下。

源文本中的初始“格式”将是： 换行符，空格和制表符。请注意，换行符和手动换行符（与DTP软件一样）不是一回事，反之亦然，某些稀有语言可能 允许其他格式的字符，尽管我从未听说过。

注释不是代码的可执行部分，因此，如果人们知道注释是否确实是注释，则可以重新格式化注释而没有太大的风险。所以首先要看的是注释如何标记。

关于初始纯文本格式的一些基础知识是很好的。例如，对于Python，有PEP8样式指南。尽管该格式指南是为Python编写的，但可以用作主要语言（例如C / C ++和Java）的参考。如有疑问，研究各种示例项目可能会有所帮助。

因此，第一个原则是：不要更改源文本。 我将通过一个清单-确保：

• 在任何阶段都不会发生字符自动替换。
• 不会对文本进行任何编辑（除非您100％确定必须完成）。
• 没有换行出现。
• 压痕在视觉上得以保留并保持一致（ 每个压痕级别大约4 x宽度）。
• 初始（零）缩进级别应可见。
• 定义的样式不会破坏语法的格式（如果使用语法突出显示）。
• 用纯文本格式备份源，以便能够重新检查原始格式或重新开始。
• 行号（如果存在）应该完整无缺，尤其是在解释中引用它们时。

实际上，如果原始源的格式正确，则根本就不需要换行。如果仍然出现并不可避免地出现换行，则最常见的解决方案是单层悬挂缩进（请参见上面的链接的PEP）。如果需要换行，最好参考样式指南或作者。

仍有一些较小的“空白”字符可能需要替换。由于源可以包含制表符，因此排版人员当然必须确保每行开头的所有制表符保持一致，即，嵌套的缩进在视觉上得以保留，并且下一个缩进级别均具有相同的宽度（大约4 x  每一级压痕的宽度）。

理想情况下，用空格字符或混合的空格和制表符制作的压痕应替换为表格（或用DTP软件可以更好地处理嵌套压痕），因此，如果需要，调整压痕可能会更容易。
当然，可能会留有空格，但是在更改字体时可能更难管理宽度，在表格列中更难以对齐内线缩进。

等宽字体+空格

请注意，如果源是有意地用空格格式化的，并且仅打算以等宽字体读取（例如ASCII图或ASCII-art），则应该完全保留空格，但是此决定应从头开始。在这种情况下，“ Courier New”字体是最常见的。我仍然建议不要使用等宽字体，因为当今越来越少的新人们选择等距字体进行编码，并且在校对的情况下，按比例字体将提供更好的阅读体验。

通常，压缩（例如Arial窄）或较小的字体可能会更好：与正文相比，它更加强调重点，它将使代码更紧凑，从而减少出现不必要的换行的可能性。

我认为这里可以画一条线，如果完成上述操作，则至少在没有颜色的纯单字体代码块中，一切正常的可能性为99％。

工具和高级格式

此外，通过使用语法突出显示可以大大改善外观。

• 彩色打印或屏幕查看：在全彩色布局中，可以使用突出显示的每个功能，因此这是最佳情况，但是打印可能会改变颜色。

• 灰度或黑白打印：当然，这里可以使用粗体（例如关键字）或斜体（例如注释），但请注意，颜色将转换为灰色，并具有所有后果。例如，显示为灰色的注释在显示屏上看起来不错，但在纸上可能变得太白。

最重要的问题是，版面设计者是否具有可以以可读形式表示代码的工具。幸运的是，有很多免费的代码编辑工具，其中最著名的（对于Windows）是：Notepad ++，VSCode和Visual Studio。但是请注意，制表符可能会隐式自动转换为空格。

在Notepad ++中，有一个将代码导出为RTF的选项，它将保留源的所有格式和语法突出显示。

如果布局不需要在代码演示中更改文本流，则可以直接使用图像（屏幕快照）–它不如文本灵活，但可以保留100％的格式和行号，并可以节省大量时间。例如，以文本形式保存行号可能会比较棘手。另外，导出为PDF是一个很好的选择–但是并非所有DTP软件都可以嵌入PDF，并且在打印为PDF时某些格式可能会丢失。

例如，我在Notepad ++中的Python代码设置如下所示：

这只是为了说明，一个人可以直接使用屏幕截图，而这实际上可能是最简单的方法。有多种工具可以帮助屏幕捕获–一个工具可能需要“拼接”屏幕以获得更高分辨率的图像。

当然，配色方案是由个人决定的，在编辑器的样式配置器中定义，该配置器已经知道受支持的语言，因此即使人不知道语法也很难进行错误的格式化。在这里，一般的排版规则应该起作用：没有太多的颜色，一致的字体，缩进，舒适的行距。

用于自定义语言定义的其他工具/插件也很常见，但是它们需要语法知识。

在HTML中，有一个标记集<code> ... </ code>告诉读者/解释器绝对按字面意义对待内容。同样，<pre> ... </ pre>的功能也差不多。作为经常不得不排版公式，方程式和代码以进行发布的人，我还主张使用IMAGES来执行此操作...为有问题的项创建.gif或.jpg或.png。

另一个因素是，代码通常以Courier等宽字体或其他等宽字体呈现，因为它向读者发信号或电报说它不是正文。我赞成这种风格的选择，我认为这很有道理。

在大多数“传统”排版系统中，相当高复杂度的数学方程式极其耗时……而且充满错误。