vscode添加头部和函数注释

### VSCode 中添加代码注释和文件头部描述注释的最佳实践 #### 插件推荐 为了简化在 VSCode 中编写 Python 文件头部注释和函数注释的过程，可以安装 `koroFileHeader` 插件[^1]。该插件能够自动为新创建的文件生成标准的头部注释模板，并支持通过快捷键快速生成函数注释。 --- #### 配置方法 以下是配置 `koroFileHeader` 的最佳方式： 1. **全局设置** 打开 VSCode 设置 JSON 文件（可通过菜单栏中的 `Preferences -> Settings -> Open Settings (JSON)`），并添加以下内容来定义默认的头部注释结构[^2]： ```json { "editor.fontSize": 15, "fileheader.customMade": { "Description": "", "Author": "Your Name", "Date": "Do not edit", "LastEditTime": "Do not edit", "FilePath": "Do not edit" }, "fileheader.cursorMode": { "description": "", "event": "", "param": "", "return": "" }, "fileheader.configObj": { "prohibitAutoAdd": ["json", "md"] } } ``` 上述配置中，“Author” 字段应替换为你自己的名字或其他标识符；“Description” 可用于填写当前文件的功能概述。 2. **启用功能** 安装完成后，在新建文件时会自动生成带有日期、作者和其他元数据的头部注释。对于已有文件，则可以通过右键菜单选择 “Insert File Header” 来手动插入头部注释。 3. **函数注释生成** 编写函数时，只需输入函数签名后按回车，随后按下指定快捷键即可触发插件生成标准化的 docstring 注释。例如，Python 函数的标准 Docstring 格式通常遵循 Google 或 NumPy 风格。 --- #### 示例代码 以下是一个完整的 Python 脚本及其对应的头部注释和函数注释示例： ```python """ @FileName: example.py @Description: This file demonstrates how to use koroFileHeader plugin. @Author: Your Name @Date: Do not edit """ def add_numbers(a: int, b: int) -> int: """ Add two numbers and return the result. Args: a (int): The first number. b (int): The second number. Returns: int: Sum of the two input numbers. """ return a + b ``` --- #### 注意事项 - 如果发现某些情况下无法正常工作，请确认是否已禁用其他可能冲突的扩展程序。 - 对于不需要头部注释的特定文件类型（如 `.json`, `.md` 等），可以在 `"prohibitAutoAdd"` 列表中声明例外情况。 ---