让你的代码开口说话！DeepSeek 自动注释脚本全面解析

开发者们常常面对这样一个难题：代码写得飞快，但注释却懒得添加。等到回头整理时，早已忘记当初写代码的思路。现在有了DeepSeek 自动注释脚本，你只需要专注于代码实现，注释交给它就好！今天我们不仅讲解这款神器的强大功能，还将逐步解析每一部分代码，让你彻底掌握它的工作原理。

yjlin1002

547人浏览 · 2025-03-28 17:46:40

yjlin1002 · 2025-03-28 17:46:40 发布

开发者们常常面对这样一个难题：代码写得飞快，但注释却懒得添加。等到回头整理时，早已忘记当初写代码的思路。
现在有了DeepSeek 自动注释脚本，你只需要专注于代码实现，注释交给它就好！
今天我们不仅讲解这款神器的强大功能，还将逐步解析每一部分代码，让你彻底掌握它的工作原理。

💻 脚本整体架构

脚本名称：add_comments.py
脚本功能：

自动为代码文件添加结构化注释，不改动代码逻辑。
支持Python、Shell (Bash)、C++、JavaScript、Java等多种编程语言。
通过DeepSeek API调用，实现精准注释。
代码风格清晰可读，行内注释和分组注释搭配使用。

🗺️ 脚本架构解析

整个脚本分为以下几个模块：

脚本说明和依赖导入
API Key 读取模块
目标代码读取模块
代码语言检测模块
代码清理和注释生成模块
命令行参数解析模块
注释结果保存模块
脚本入口

1. 脚本说明和依赖导入

首先是脚本的元信息和依赖导入：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import os
import sys
import argparse
import logging
import re
from openai import OpenAI

logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

解析：

脚本元信息：指定解释器为 Python 3，支持 UTF-8 编码。
导入模块：
- os 和 sys：用于文件和系统操作。
- argparse：用于解析命令行参数。
- logging：日志管理，记录脚本执行状态。
- re：正则表达式模块，进行字符串清理。
- openai：调用 DeepSeek API，生成代码注释。
日志配置：设置日志级别为 INFO，便于跟踪执行状态。

2. API Key 读取模块

功能： 从指定文件中读取 DeepSeek API Key。

def read_api_key(api_key_file: str) -> str:
    """从指定文件中读取API密钥"""
    if not os.path.exists(api_key_file):
        raise FileNotFoundError(f"未找到 API Key 文件: {api_key_file}")
    with open(api_key_file, "r", encoding="utf-8") as f:
        key = f.read().strip()
    if not key:
        raise ValueError("API Key 文件为空，请检查文件内容。")
    return key

解析：

检查 API Key 文件是否存在，若不存在则抛出异常。
从文件中读取 API Key，并去除多余空格。
若读取结果为空，则抛出值错误异常。

3. 目标代码读取模块

功能： 读取待注释的代码文件内容。

def read_target_script(script_path: str) -> str:
    """读取目标代码文件内容"""
    if not os.path.exists(script_path):
        raise FileNotFoundError(f"目标代码文件不存在: {script_path}")
    with open(script_path, "r", encoding="utf-8") as f:
        return f.read()

解析：

检查代码文件是否存在，若不存在则报错。
使用 with open() 打开文件，读取完整内容后返回。

4. 代码语言检测模块

功能： 根据文件扩展名自动识别编程语言。

def detect_language(script_path: str) -> str:
    """根据文件扩展名检测编程语言"""
    ext = os.path.splitext(script_path)[1].lower()
    language_map = {
        ".py": "Python",
        ".sh": "Shell",
        ".cpp": "C++",
        ".c": "C",
        ".js": "JavaScript",
        ".java": "Java"
    }
    return language_map.get(ext, "未知语言")

解析：

提取文件扩展名，并通过字典匹配返回相应语言。
若无法匹配，则返回“未知语言”。

5. 代码清理和注释生成模块

功能： 调用 DeepSeek API 生成带注释代码，同时清理不必要的 Markdown 标签。

def clean_markdown_tags(content: str) -> str:
    """清理残留的Markdown标记并保留分组注释"""
    content = re.sub(r'^```[a-zA-Z]*\s*', '', content, flags=re.MULTILINE)
    content = re.sub(r'\n```\s*$', '', content)
    return content.strip()

解析：

使用正则表达式去除代码中的 Markdown 标记，例如：
- 删除代码块开头的 python、bash 等标记。
- 删除代码块结尾的 ```标记。

6. 注释生成模块

功能： 使用 DeepSeek API 为代码生成带注释的版本。

def generate_commented_code(api_key: str, script_content: str, language: str) -> str:
    """调用API生成带注释的代码"""
    client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
    prompt = f"请为以下 {language} 代码添加结构化注释..."
    try:
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": prompt}]
        )
        return clean_markdown_tags(response.choices[0].message.content)
    except Exception as e:
        logging.error(f"API调用失败: {e}")
        raise

解析：

构造 API 请求并发送。
捕获异常并进行日志记录，防止程序崩溃。

7. 命令行参数解析模块

功能： 使用 argparse 解析命令行参数。

def parse_arguments() -> argparse.Namespace:
    """解析命令行参数"""
    parser = argparse.ArgumentParser(description="自动为代码文件添加结构化注释")
    parser.add_argument("script_path", type=str, help="目标代码文件路径")
    return parser.parse_args()