---
fid: 20251026-120000
title: Python注释与文档字符串使用指南
tags: comment, docstring
---

# Python注释与文档字符串使用指南

**难度**: 1

**时长**: 15 min

## 核心概念

### 1. Python文件结构层次
```
┌─────────────────────────────────────────┐
│ 文件头部注释 (File Header Comments)       │ ← # 开头的单行注释
├─────────────────────────────────────────┤
│ 模块文档字符串 (Module Docstring)         │ ← 三引号字符串
├─────────────────────────────────────────┤
│ 导入语句 (Import Statements)             │
├─────────────────────────────────────────┤
│ 函数/类定义等代码内容                      │
└─────────────────────────────────────────┘
```

### 2. 文件头部注释 vs 模块文档字符串

| 类型 | 语法 | 位置 | 用途 | 是否可通过`__doc__`访问 |
|------|------|------|------|------------------------|
| 文件头部注释 | `#` 单行注释 | 文件最顶部 | 版权信息、作者、创建日期等元数据 | 否 |
| 模块文档字符串 | 三引号字符串 `"""` | 在import语句之前，其他代码之后 | 模块功能描述、使用方法等 | 是 |

## Python文件结构与注释

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Copyright 2024 Your Name
# Created: 2024-07-29
# Version: 1.0
# License: MIT

"""
example_module - 这是一个示例模块

这个模块演示了Python中正确的注释和文档字符串使用方法。
它包含了各种类型的注释示例，帮助理解不同注释的适用场景。

主要功能:
    - 提供示例函数
    - 展示类定义
    - 演示文档字符串的使用

示例:
    >>> import example_module
    >>> result = example_module.my_function(5)
"""

import os
import sys

def my_function(param):
    """
    执行特定操作的示例函数
    
    参数:
        param (int): 输入参数描述
        
    返回:
        str: 处理后的结果字符串
        
    抛出:
        ValueError: 当参数无效时
        
    示例:
        >>> my_function(10)
        '处理结果: 20'
    """
    return f"处理结果: {param * 2}"

class MyClass:
    """
    示例类定义
    
    这个类展示了如何在类级别使用文档字符串，
    以及如何为方法和属性添加文档。
    
    属性:
        name (str): 实例名称
        value (int): 存储的数值
    """
    
    def __init__(self, name, value):
        """
        初始化MyClass实例
        
        参数:
            name (str): 实例名称
            value (int): 初始数值
        """
        self.name = name
        self.value = value
    
    def display(self):
        """显示实例信息"""
        return f"{self.name}: {self.value}"
```

## 各类注释的正确用法

### 1. 文件头部注释（单行注释 `#`）
```python
# 版权信息
# 作者信息
# 创建日期
# 版本号
# 许可证信息
# 文件编码声明
# Shebang行（仅限可执行脚本）
```

### 2. 模块文档字符串（三引号 `"""`）
```python
"""
模块名称
模块功能概述

详细描述:
    模块的主要功能和特点

使用示例:
    基本的导入和使用方法

注意事项:
    使用时的特殊说明
"""
```

### 3. 函数/方法文档字符串
```python
def function_name(parameters):
    """
    函数功能简要描述
    
    详细描述函数的作用、算法说明等
    
    参数:
        param1 (type): 参数描述
        param2 (type): 参数描述
        
    返回:
        type: 返回值描述
        
    抛出:
        ExceptionType: 异常情况说明
    """
```

### 4. 类文档字符串
```python
class ClassName:
    """
    类功能描述
    
    属性:
        attr1 (type): 属性描述
        attr2 (type): 属性描述
        
    方法:
        method1: 方法功能描述
        method2: 方法功能描述
    """
```

### 5. 行内注释（单行注释 `#`）
```python
result = calculate_value()  # 计算结果并缓存
```

## 重要注意事项

1. **模块文档字符串的位置**：必须在import语句之前，但可以在文件头部注释之后
2. **文档字符串的可访问性**：只有三引号文档字符串可以通过`__doc__`属性访问
3. **工具兼容性**：文档生成工具（如Sphinx）只识别三引号文档字符串
4. **执行影响**：三引号字符串在运行时会被创建为字符串对象，而`#`注释完全被忽略

## 最佳实践建议

1. **混合使用**：合理结合文件头部注释和模块文档字符串
2. **一致性**：在项目中保持统一的注释风格
3. **及时更新**：代码修改时同步更新相关注释
4. **适度注释**：避免过度注释，让代码自文档化

通过这种清晰的区别和使用方式，可以确保Python代码既具有良好的可维护性，又能充分利用Python的文档工具生态系统。