对于面向研发人员交付的平台型或中间件型的软硬件产品，通常需要随产品同时发布开发指南，以指导用户如何基于产品进行二次开发。在这类文档中，自然少不了代码段，以及对代码段的说明。那么，在文档中引用/说明代码段时，需要注意什么呢？
大家好，我是睿齐，一个技术传播者。
区分添加/配置/示例代码段
虽然代码段看起来都一个样，但是当代码段被写进了文档里，存在着微妙的差异，需要加以甄别，并进行相应处理。
个人认为，常用的代码段可分成3种类型：添加代码段、配置代码段和示例代码段。
添加代码段
代码段可直接拾取并添加到用户工程中使用，无需经过任何修改或配置。
示例：在 file.m 文件中引入头文件：
#import <HeaderFile1.h>
#import <HeaderFile2.h>
#import <HeaderFile3.h>
配置代码段
代码段包含配置项，需结合具体使用场景，填写相关配置后使用。
对于配置代码段，需明确标识配置项，并相应给出具体配置说明；代码段中的配置项，与配置说明中的配置项，需一一对应，便于用户准确识别配置项，并进行正确设置。
示例：在 file.m 文件的 method 方法中，添加代码段，填写配置项，进行相应操作。
para1 = ${val1}; //配置项1
para2 = ${val2}; //配置项2
具体配置说明如下：
配置项 | 说明 |
val1 | 具体内容略。 |
val2 | 具体内容略。 |
示例代码段
示例代码段常常是在已有开发说明的基础上，结合典型使用场景，给出的完整示例。
对于示例代码段，需说明典型使用场景，但无需对逐行代码进行详细说明。
索引接口说明
如代码段中涉及的接口已在接口说明中给出详细参数说明，则索引至相关内容，便于用户参考使用。
示例：调用 method() 接口，进行相应操作。
其中method()为跳转至相应接口说明的链接。
明确代码段位置
代码说明中需明确代码段所在位置，包括但不限于工程目录—所在文件—某方法等，在添加代码段场景，便于用户定位添加位置；在示例代码段场景，便于用户在提供的Demo工程中查找相应位置。如添加代码段无位置限制，则说明“在任意位置添加”。
错误：添加代码段。
正确：在 file.m 文件的 method 方法中，添加代码段。
正确：在任意位置添加代码段。
明确操作目的
代码说明需尽可能明确操作动作及操作目的，便于用户理解操作逻辑。
错误：添加以下代码段。
正确：添加以下代码段，定义Application类，编写OnCreate方法启动服务。
与Demo保持一致
由于研发人员热爱代码胜于文档，因此，通常会随开发指南提供Demo工程。在这种情况下，文档中的代码段及说明，需与Demo工程中的代码及相应信息保持一致。
行内/独立代码段
行内代码段
如代码段长度较短，可在行内使用。
示例：执行 commond 命令，进行相应操作。
独立代码段
如代码段长度较长，可另起一行，独立使用。
示例：执行以下命令，进行相应操作。
commond para1=val1, para2=val2, ...
代码段可执行
在文档中出现的代码段，需可执行。
以上，就是在文档中引用/说明代码段的注意事项。无论是对外交付的文档开发场景，或者是日常工作中设计/策划方案的写作场景，都可以参考借鉴，希望能够帮助你输出更加易读易用的技术知识/信息。
相关文章：
其他推荐：
实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播
这次他们说好要“讲真的” | 传播
在座都别吵了，你们还有我 | 技术传播
睿齐
技术传播从业者
品牌内容策划
自由摄影师
自由撰稿人
汪力迪
公众号：techcomm / htstory
微信号：bgrichi
邮箱：hash_0813@163.com
4260
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
