代码块和代码注释

技术文档中插入代码块建议遵循以下规范。

  • 代码块前后必须加上一行空行。

  • 代码块要注意缩进。例如,当前代码块属于列表项下的内容,则要在该列表项的缩进基础上再缩进四格。

  • 如果前端支持,建议高亮代码块,方便阅读。

  • 如果前端支持,建议为代码块加上可供用户直接复制代码的按钮,提高文档易用性。

代码注释一般出现在多行代码块中。技术文档中插入代码注释建议遵循以下规范。

  • 一行注释不能太长,太长时应适当进行断句并切分到下一行。

  • 一行注释末尾建议加上标点符号,一般是句号;与下一行的内容承接时,用逗号。

  • 必须根据代码块中定义的语法选择相应的注释符,不能自创注释符。