4.5 代码示例

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

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 推荐

代码注释使用中文

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

警告

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