VSCode添加Python、Java注释技巧、模板
一、代码日常注释很重要
1、增加代码可读性，清晰、准确的注释，能让开发者迅速明白一段代码的意图、功能和实现逻辑，大幅提升代码的可读性。尤其是在大型项目中，复杂的业务逻辑和众多的代码文件，如果缺乏注释，阅读起来就会很吃力。
2、从代码维护的角度看，随着时间推移，项目需求变更、代码修改在所难免。当再次审视几个月甚至几年前编写的代码时，没有注释的辅助，理解代码的功能和修改要点会变得异常困难，而清晰的注释则能让维护工作变得轻松许多。
3、在团队协作开发中，注释更是沟通的桥梁。不同开发者的编程风格和思维方式存在差异，通过注释，团队成员可以将自己的设计思路、代码逻辑传递给他人，使整个团队对项目的理解保持一致，提高开发效率，减少因沟通不畅导致的错误。
VS Code 添加注释模板，以Java和Python为例
VS Code，作为一款广受欢迎的轻量级代码编辑器，以其强大的功能、丰富的插件生态和跨平台的特性，成为众多开发者的首选。它支持多种主流编程语言，如 JavaScript、Python、C++、Java 等 ，为开发者提供了统一且高效的开发环境。凭借着轻量与高性能的特点，VS Code 启动速度快、内存占用低，即使在处理大型项目时也能保持流畅的运行效率，极大地提升了开发体验。
注释模板，简单来说，就是一种预定义的注释格式。通过注释模板，开发者只需按照特定的结构和占位符，填入相应的信息，就能快速生成规范的注释。这不仅节省了手动编写注释的时间，还能确保项目中注释风格的一致性，使代码更加整洁、易读。例如，在定义一个复杂的函数时，使用注释模板可以迅速生成包含函数功能描述、参数说明、返回值解释等内容的注释，让阅读代码的人能够快速理解函数的用途和使用方法。
Java 注释模板设置与使用
（一）准备工作
在 VS Code 中进行 Java 开发，首先要确保安装了 Java 扩展包。打开 VS Code，点击左侧的扩展图标（或者使用快捷键 Ctrl+Shift+X ），在搜索框中输入 “Java Extension Pack” ，点击安装按钮。安装完成后，还需确认 Java 语言支持设置已启用。点击左下角的齿轮图标，选择 “Settings”，在搜索框中输入 “Java” ，确认相关设置已开启。
（二）自动生成注释
当我们创建好 Java 类和方法后，生成注释变得轻而易举。在类或方法的上方，按下快捷键 Alt + Shift + J （点击小灯泡，更多操作，Add JavaDoc），即可快速生成 JavaDoc 格式的注释。这种注释以 “/*” 开头，以 “/” 结尾，中间包含了详细的描述信息。例如，对于一个计算两个整数之和的方法：
public int add(int a, int b) {return a + b;}使用快捷键生成的注释如下：
/*** * @param a* @param b* @return*/public int add(int a, int b) {return a + b;}可以看到，生成的注释中包含了方法的参数和返回值的占位说明，方便我们进一步补充详细的描述信息，使代码的功能和使用方法一目了然。
（三）Java自定义注释模板
虽然自动生成的注释已经提供了基本的结构，但有时我们希望注释能够包含更多个性化的信息，如作者、创建时间等。这时候，就可以通过自定义注释模板来实现。打开 VS Code 的设置（可以通过左下角的齿轮图标进入），在搜索框中输入 “Java Doc” ，找到 “Java › Templates: Type Comment” 设置项。点击该项的编辑按钮，进入 JSON 编辑模式，我们可以在这里使用变量来构建更丰富的注释模板。
例如，使用以下配置：
"java.templates.typeComment": ["/**"," * @author ${user}"," * @date ${date} ${time}"," * @description ${todo:write description here}"," */"]其中，“({user}”会自动替换为系统登录用户名，“){date}” 和 “({time}”分别表示系统日期和时间，“){todo:write description here}” 是一个占位提示，提醒我们填写方法的描述信息。设置完成后，再次使用快捷键生成注释，就会看到自定义的内容出现在注释中：
/*** @author John* @date 2024-10-10 15:30:00* @description write description here* * @param a* @param b* @return*/public int add(int a, int b) {return a + b;}这样，我们就可以根据项目的需求和个人习惯，定制出符合自己风格的注释模板，让代码的注释更加规范和有价值。
（三）使用User Snippets生成Java注释
代码注释模板：
ccj 文件头
ccmtj文件方法
使用方法：输入前缀，再按Tab键
{// Place your 全局 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is // used to trigger the snippet and the body will be expanded and inserted. Possible variables are: // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. // Placeholders with the same ids are connected.// Example:// "Print to console": {// "scope": "javascript,typescript",// "prefix": "log",// "body": [// "console.log('$1');",// "$2"// ],// "description": "Log output to console"// }"ccj": {• "prefix": "ccj",• "body": [• "/**",• "* @description 功能描述",• "* @author ZhangSan",• "* @since $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND",• "*/"• ],},"ccmtj": {• "prefix": "ccmtj",• "body": [• "/**",• "* description: ",• "* @since @since $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND",• "* @param ",• "* @return ",• "*/"• ],}}Python 注释模板设置与使用
（一）开发环境准备
在开始设置 Python 注释模板之前，确保你的开发环境已准备就绪。你需要安装好 Python 环境，建议使用 Python 3.6 及以上版本，以获得更好的功能支持和性能优化。同时，在 VS Code 中安装 Python 扩展，打开 VS Code，点击左侧的扩展图标，搜索 “Python” ，然后点击安装按钮。安装完成后，VS Code 将具备对 Python 代码的语法高亮、智能代码补全、代码调试等强大功能，为 Python 开发提供良好的支持。
（二）基础配置
打开 VS Code，按下快捷键 Ctrl + Shift + P ，打开命令面板。在命令面板中输入 “Preferences: Open User Snippets” ，然后选择 “python.json” ，这将打开 Python 用户代码片段的配置文件。在这个文件中，我们可以定义各种代码片段，包括注释模板。例如，我们可以添加以下基本的函数注释模板：
"Function Docstring": {"prefix": "func_doc","body": ['\"\"\"',"Function: ${1:describe the function's purpose}","","Args:"," ${2:arg1} (${3:type}): ${4:describe arg1}"," ${5:arg2} (${6:type}): ${7:describe arg2}","","Returns:"," ${8:return_type}: ${9:describe the return value}",'\"\"\"'],"description": "Function docstring template"}这里，“prefix” 是触发代码片段的前缀，当我们在 Python 文件中输入 “func_doc” 并按下 Tab 键时，就会自动插入这个注释模板。“body” 部分定义了注释的具体内容，使用 “${n:description}” 这样的占位符来提示我们填写相应的信息，其中 “n” 是占位符的编号，“description” 是提示信息。
（三）创建注释模板
除了函数注释模板，我们还可以创建文件注释模板。在 “python.json” 文件中继续添加以下内容：
"File Docstring": {"prefix": "file_doc","body": ['\"\"\"',"Module: ${1:module name}","Description: ${2:describe the module's function}","Author: ${3:author name}","Date: ${4:${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}}",'\"\"\"'],"description": "File docstring template"}这样，当我们在 Python 文件开头输入 “file_doc” 并按下 Tab 键时，就会生成包含模块名称、描述、作者和日期等信息的文件注释模板。通过合理使用占位符，我们可以快速生成规范的注释，提高代码编写的效率和规范性。
注释文件模板示例参考：
{// Place your 全局 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and // description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope // is left empty or omitted, the snippet gets applied to all languages. The prefix is what is // used to trigger the snippet and the body will be expanded and inserted. Possible variables are: // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. // Placeholders with the same ids are connected.// Example:// "Print to console": {// "scope": "javascript,typescript",// "prefix": "log",// "body": [// "console.log('$1');",// "$2"// ],// "description": "Log output to console"// }"ccpy": {• "prefix": "ccpy",• "body": [• "'''",• "@Description: :",• "@Date :$CURRENT_YEAR/$CURRENT_MONTH/$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND",• "@Author :ZhangSan",• "@version :1.0",• "'''",• // "", • // "$0" • ],},"ccmtpy": {• "prefix": "ccmtpy",• "body": [• "\"\"\"",• "",• "Parameters",• "---------",• "@param : TYPE",• " DESCRIPTION",• "",• "Returns :",• "-------",• "@param : TYPE",• " DESCRIPTION ",• "\"\"\"",• "",• "$0"• ],}}（四）高级步骤
如果我们希望在多个项目中共享自定义的代码片段，可以在 VS Code 的用户设置中，找到 “snippets” 相关的设置项，将自定义代码片段的目录添加到 “snippets” 的路径中。例如，我们在用户主目录下创建一个 “my_snippets” 目录，将 “python.json” 文件放入其中，然后在 VS Code 设置中添加如下配置：
"files.associations": {"*.py": "python"},"[python]": {"editor.snippetSuggestions": "top","editor.snippets": {"python": ["${userHome}/my_snippets/python.json"]}}