4.3 代码示例

技术文档中代码示例的展示规范。

R-080 推荐

代码示例必须可直接运行

技术文档中的代码示例应尽可能完整且可直接运行。如果需要省略部分代码，应使用注释说明省略的内容。

Python API 调用示例

import requests

# API 端点地址
url = "https://api.example.com/v1/documents"

# 设置请求头
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

# 发送 GET 请求
response = requests.get(url, headers=headers)

# 检查响应状态
if response.status_code == 200:
    data = response.json()
    print(f"获取到 {len(data)} 个文档")
else:
    print(f"请求失败: {response.status_code}")

R-081 推荐

代码注释使用中文

面向中文读者的文档中，代码注释应使用中文。变量名和函数名保持英文。注释应解释「为什么」而不仅仅是「做了什么」。

DITA 主题示例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN"
  "topic.dtd">
<topic id="install_guide">
  <title>安装指南</title>
  <body>
    <section>
      <title>系统要求</title>
      <ul>
        <li>操作系统：Windows 10 或 macOS 12 以上</li>
        <li>内存：8 GB 以上</li>
        <li>磁盘空间：2 GB 可用空间</li>
      </ul>
    </section>
  </body>
</topic>

警告

代码示例中不要包含真实的 API 密钥、密码或敏感信息。使用占位符（如 YOUR_API_KEY）替代。