.作者：@Carlos Mucuho
原文：https://blog.logrocket.com/automate-code-commenting-using-vs-code-ollama/
概述
在软件开发中，代码注释扮演着至关重要的角色。它们不仅解释复杂的逻辑，记录决策过程，还为未来的开发者提供上下文信息。尽管有人认为编写良好的代码应该是自解释的，但其他人强调注释在捕捉特定实现背后的推理方面的重要性。随着 AI 驱动的编码助手如 GitHub Copilot 的流行，自动化注释生成的想法引发了关于 AI 是否能真正捕捉到使注释有价值的人类洞察力的讨论。
本文介绍如何构建一个 VS Code 扩展程序，利用 Ollama.js 库和本地大型语言模型 (LLM) 自动生成程式码注释。Ollama 本身不是一个编程助手，而是一个允许开发人员运行大型语言模型 (LLM) 以提高生产力的工具，通过本教程，您将学习如何利用 AI 编码工具简化文档流程，而无需共享您的数据或支付昂贵的订阅费用。
最终呈现的效果：
一、Ollama 设置
1、下载并安装 Ollama：根据您的操作系统从 Ollama 官方网站下载相应的安装程序。
要在 Windows 上安装 Ollama，请下载可执行文件并运行它。Ollama 将自动安装，您就可以开始使用它了。
对于 Mac，在下载 Ollama for MacOS 后，解压文件并将
Ollama.app文件夹拖到您的 Applications 文件夹中。移动应用程序后，安装就完成了。对于 Linux 用户，安装 Ollama 就像在您的终端中运行以下命令一样简单：
curl -fsSL https://ollama.com/install.sh | sh2、启动 Ollama 服务：打开 Ollama 应用程序或在终端中运行 ollama serve 命令。
Ollama 安装完成后，您可以开始与 LLM 进行交互。在运行任何命令之前，您需要通过打开应用程序或在终端中运行以下命令来启动 Ollama：
ollama serve此命令启动 Ollama 应用程序，允许您使用可用的命令。它还启动在端口 11434 上运行的 Ollama 服务器。您可以通过打开一个新的浏览器窗口并导航到 http://localhost:11434/ 来检查服务器是否正在运行。
3、获取和运行模型：使用 ollama pull 命令获取模型，并使用 ollama run 命令运行模型。
要从 Ollama 注册表中拉取模型而不运行它，请使用 ollama pull 命令。例如，要拉取 phi3.5 模型，请运行以下命令：
ollama pull phi3.5此命令获取模型并使其可供以后使用。
您可以使用以下命令列出所有已拉取的模型：
ollama list这将显示模型列表及其大小和修改时间：
NAME ID SIZE MODIFIED
phi3.5:latest 61819fb370a3 2.2 GB 11 days ago
llava:latest 8dd30f6b0cb1 4.7 GB 2 weeks ago
phi3:latest 64c1188f2485 2.4 GB 3 months ago
csfm1993:~$要立即拉取和执行模型，请使用 ollama run 命令。例如，要运行 phi3.5，请运行：
ollama run phi3.5此命令拉取模型（如果尚未拉取），并开始执行，以便您可以立即开始查询它。
您应该在您的终端中看到以下内容：
csfm1993:~$ ollama run phi3.5
>>> Send a message (/? for help)
>>>在本教程中，您将使用 phi3.5 模型为给定的程式码块生成注释。选择这种语言模型是因为它在大小和性能之间取得了平衡 —— 虽然它很紧凑，但它提供了强大的结果，使其成为构建概念验证应用程序的理想选择。
phi3.5 模型足够轻巧，可以在 RAM 有限且没有 GPU 的计算机上高效运行。如果您有 GPU，请随时运行更大的 LLM。
将以下提示发送到模型：
complete code: " const express = require('express') const app = express() const port = 3000 app.get('/', (req, res) => { res.send('Hello World!') })
app.listen(port, () => { console.log(`Example app listening on port ${port}`) }) " Given the code block below, write a brief, insightful comment that explains
its purpose and functionality within the script. If applicable, mention any inputs expected in the code block. Keep the comment concise (maximum 2 lines). Wrap
the comment with the appropriate comment syntax (//). Avoid assumptions about the complete code and focus on the provided block. Don't rewrite the code block.
code block: " app.get('/', (req, res) => { res.send('Hello World!') }) "提示要求 phi3.5 模型解释给定程式码块中发生的事情。您应该得到类似于以下的答案：
// This Express.js route handler responds to GET requests at the root URL ('/'), sending back a plain text 'Hello World!' message as an HTTP response. No
additional inputs are required for this specific block of code, which serves as a basic setup example within a web server context.模型返回一个带有指定注释语法的注释，后面是解释。与模型交互完成后，发送命令 /bye 结束聊天。
本教程使用 phi3.5 模型生成注释，它体积小、性能强，适合构建概念验证应用程序。
二、创建和配置项目
1、使用 Yeoman 和 VS Code Extension Generator 创建一个新的 VS Code 扩展程序项目。
npx --package yo --package generator-code -- yo code建立一个新的 VS Code 扩展程序项目。你需要选择 TypeScript 作为项目语言，并填写其他必要的字段，例如扩展程序名称、标识符和描述等。
2、使用 npm install ollama cross-fetch 命令安装必要的模块。
npm install ollama cross-fetch安装与 Ollama 服务器交互所需的模块：
ollama: 提供与大型语言模型（LLM）互动的工具和实用程序，用于与 Ollama 伺服器通讯并发送提示以生成代码注释。
cross-fetch: 为 Node.js 带来 Fetch API 支持，允许在原生不支持 Fetch 的环境中获取资源，例如 API 请求。用于向 Ollama 服务器发出 HTTP 请求，避免 LLM 生成响应时间过长导致的 HTTP 请求超时错误。
3、在 package.json 文件中，确保 vscode 版本与您系统中安装的 VS Code 版本匹配。
"engines": {
"vscode": "你的 VS Code 版本"
},在 package.json 中，找到 engines 属性，并将 vscode 的值设置为你系統中安裝的 VS Code 版本。
4、将默认的 "Hello World" 命令替换为 "Generate Comment" 命令。
"contributes": {
"commands": [
{
"command": "commentgenerator.generateComment",
"title": "Generate Comment"
}
]
},在 package.json 中，找到 contributes.commands 部分，将原来的 "Hello World" 命令替换为 "Generate Comment" 命令，并将其 ID 设置为 commentgenerator.generateComment。
打开 extension.ts 文件，将 activate 函数内的代码替换为以下代码：
import * as vscode from 'vscode';
export function activate(context: vscode.ExtensionContext) {
console.log('Congratulations, your extension "commentgenerator" is now active!');
const generateCommentCommand = vscode.commands.registerCommand('commentgenerator.generateComment', async () => {
vscode.window.showInformationMessage('Generating comment, please wait');
});
context.subscriptions.push(generateCommentCommand);
}
5、使用 npm run watch 命令监控项目更改并自动编译。
npm run watch在终端中运行此命令，启动 TypeScript 编译器的监控模式。它会在你修改项目文件时自动重新编译项目。
三、构建提示
1、使用 getScriptContext 函数获取当前文件的完整内容作为代码上下文。
import * as vscode from 'vscode';
/**
* 获取当前文件的完整文本作为代码上下文。
* @param editor 当前文本编辑器。
* @returns 代码上下文。
*/
function getScriptContext(editor: vscode.TextEditor): string {
const document = editor.document;
const codeContext = document.getText();
return codeContext;
}2、使用 getCodeBlock 函数从剪贴板中读取代码块。
/**
* 从剪贴板中读取代码块。
* @returns 代码块。
*/
async function getCodeBlock(): Promise<string> {
const codeBlock = await vscode.env.clipboard.readText();
return codeBlock;
}3、使用 selectCommentSyntax 函数根据文件扩展名选择适当的注释语法。
/**
* 根据文件扩展名选择适当的注释语法。
* @param editor 当前文本编辑器。
* @returns 注释语法。
*/
function selectCommentSyntax(editor: vscode.TextEditor): string {
const fileExtension = editor.document.fileName.toLowerCase().split('.').at(-1);
const commentSyntax = fileExtension === 'js' ? '//' : '#';
return commentSyntax;
}4、使用 buildPrompt 函数构建提示字符串，该字符串包含代码块、代码上下文和注释语法，并指示 LLM 生成简洁、深刻的注释。
/**
* 构建提示字符串。
* @param editor 当前文本编辑器。
* @returns 提示字符串。
*/
export async function buildPrompt(editor: vscode.TextEditor): Promise<string> {
const codeBlock = await getCodeBlock();
const codeContext = getScriptContext(editor);
const commentSyntax = selectCommentSyntax(editor);
if (codeBlock === undefined || codeContext === undefined) {
return;
}
let prompt = `
complete code: "{CONTEXT}"
Given the code block below, write a brief, insightful comment that explains its purpose and functionality within the script. If applicable, mention any inputs
expected in the code block. Keep the comment concise (maximum 2 lines). Wrap the comment with the appropriate comment syntax ({COMMENT-SYNTAX}). Avoid
assumptions about the complete code and focus on the provided block. Don't rewrite the code block.
code block: "{CODE-BLOCK}"
`;
prompt = prompt
.replace('{CONTEXT}', codeContext)
.replace('{CODE-BLOCK}', codeBlock)
.replace('{COMMENT-SYNTAX}', commentSyntax);
return prompt;
}四、使用 Ollama.js 生成注释
1、使用 Ollama 类创建一个新的 Ollama 实例，并指定主机和 fetch 函数。
import { Ollama } from 'ollama';
import fetch from 'cross-fetch';
// 创建一个新的 Ollama 实例，指定主机和 fetch 函数
const ollama = new Ollama({
host: 'http://127.0.0.1:11434',
fetch: fetch,
});2、使用 generateComment 函数发送提示到 Ollama 服务器并接收生成的注释。
3、使用 performance.now 函数记录 LLM 生成响应所需的时间。
/**
* 发送提示到 Ollama 服务器并接收生成的注释。
* @param prompt 提示字符串。
* @returns 生成的注释。
*/
export async function generateComment(prompt: string): Promise<string> {
// 记录开始时间
const t0 = performance.now();
// 发送请求到 Ollama 服务器
const req = await ollama.generate({
model: 'phi3.5', // 使用 phi3.5 模型
prompt: prompt,
});
// 记录结束时间
const t1 = performance.now();
// 计算 LLM 生成响应所需的时间
console.log('LLM took: ', t1 - t0, ', seconds');
// 返回生成的注释
return req.response;
}五、将注释添加到脚本
1、使用 getCurrentLine 函数获取当前行号。
import * as vscode from 'vscode';
/**
* 获取当前行号。
* @param editor 当前文本编辑器。
* @returns 当前行号。
*/
export function getCurrentLine(editor: vscode.TextEditor): number {
const currentLine = editor.selection.active.line;
console.log('currentLine: ', currentLine);
return currentLine;
}2、使用 addCommentToFile 函数将生成的注释添加到指定行。
3、使用 WorkspaceEdit 对象插入注释，并使用 applyEdit 函数应用编辑。
/**
* 将生成的注释添加到指定行。
* @param fileURI 文件 URI。
* @param fileName 文件名。
* @param line 行号。
* @param generatedComment 生成的注释。
*/
export async function addCommentToFile(
fileURI: vscode.Uri,
fileName: string,
line: number,
generatedComment: string,
): Promise<void> {
console.log('adding comment', line, generatedComment);
// 创建一个新的 WorkspaceEdit 对象
const edit = new vscode.WorkspaceEdit();
// 使用 insert 方法将注释插入到指定位置
edit.insert(fileURI, new vscode.Position(line, 0), generatedComment.trim());
// 应用编辑
await vscode.workspace.applyEdit(edit);
// 显示信息消息
vscode.window.showInformationMessage(`已将注释添加到 ${fileName} 的第 ${line + 1} 行`);
}
结论
本教程演示了如何使用 VS Code 和 Ollama 构建一个自动化代码注释的扩展程序。这个项目展示了如何在不共享数据或支付昂贵订阅费用的情况下，利用 LLM 模型提高生产力。
AI 阅：了解技术资讯的一种方式。
🚀可直接通过阅读原文了解详细内容。
