fdt:code-note

中文环境要求

本技能运行在中文环境下，请遵循以下约定：

• 面向用户的回复、注释、提示信息必须使用中文
• AI 内部处理过程可以使用英文
• 所有生成的文件必须使用 UTF-8 编码

---

code-note Skill

为 Flutter 项目的 Dart 源文件添加中文注释。

When to Use

• 为现有代码添加注释
• 提升代码可读性，方便团队协作
• 为遗留代码补充文档
• 为复杂逻辑添加行内说明

Example Prompts

• /fdt:code-note AlbumPage
• /fdt:code-note login_page.dart
• 给 AlbumPage 添加注释
• 帮我给这个文件写上注释

---

Command Parameters

Parameter	Description
文件名	要添加注释的文件名（支持 .dart），可带或不带扩展名

---

Execution Flow

1. Locate Target File

Use Glob to find the file:

**/*{FileName}.dart

If multiple matches found, list them and ask user to select.

2. Read File Content

Read the entire file to understand:

• Class/Widget structure and purpose
• Member variables
• Methods and their functions
• Key logic blocks

3. Analyze Code Structure

Identify elements that need comments:

Class Level

• Class/Widget purpose and responsibility
• Key features/capabilities

Member Variables

• Purpose of each variable
• Data type significance if non-obvious

Methods

• Method purpose (dartdoc style)
• Parameter descriptions
• Return value meaning
• Side effects if any

Key Logic Blocks

• Complex conditional logic
• Loops and iterations
• Callback handlers
• Data transformations
• Error handling
• State management logic (setState, Bloc, Riverpod, Provider)

4. Add Comments

Follow these rules:

Style Guidelines:

• Use Chinese comments
• Keep comments concise but informative
• Use dartdoc format (///) for method documentation
• Use single-line // for inline explanations

Comment Types:

/// 类/方法说明
/// [paramName] 参数说明
/// 返回值说明

// 单行注释说明关键逻辑

/// 成员变量说明
final String variable;

5. Apply Changes

Use Edit tool to add comments without modifying code logic.

---

Comment Priority

Priority	Element	Example
High	Public methods	void deleteUser()
High	Complex logic	Nested conditions, algorithms
High	Build methods	Widget build(BuildContext context)
Medium	Class members	final ScrollController _controller
Medium	Private methods	void _calculate()
Medium	State lifecycle	initState(), dispose()
Low	Self-explanatory code	title: Text('Hello')

---

Comment Style Examples

Widget Comment

/// 相册页面
/// 展示用户拍摄的照片/视频列表，支持查看详情、设为壁纸等功能
class AlbumPage extends StatefulWidget {

Member Variable Comment

/// 照片数据列表
final List<PhotoEntity> _photos = [];

/// 相册列表适配器
late AlbumAdapter _adapter;

Method Comment

/// 重新发布
/// [entity] 照片实体
/// [context] 上下文
/// [onStatusChange] 状态变化回调
Future<void> repost(
  PhotoEntity entity,
  BuildContext context,
  VoidCallback onStatusChange,
) async {

Logic Block Comment

// 根据上传状态显示不同提示
switch (status) {
  // 未上传状态
  case UploadStatus.idle:
    // ...
  // 上传中状态
  case UploadStatus.uploading:
    // ...
  // 上传失败状态
  case UploadStatus.failed:
    // ...
}

---

Notes

1. Do not modify code logic - Only add comments
2. Chinese comments - All comments in Chinese
3. Concise but comprehensive - Balance brevity with completeness
4. Preserve formatting - Maintain original code style
5. No redundant comments - Don't state the obvious
6. Use dartdoc style - /// for method/class docs, // for inline