开发最佳实践

代码风格

注释

  • 注释统一用英文（老的中文注释应该逐渐更改）

  • docstring 使用 Sphinx docstring format

  • FIXME, TODO, and HELP

    • FIXME: 开发者明确知道某个地方代码不优雅

    • HELP: 开发者写了一段自己不太理解，但是可以正确工作的代码

    • TODO: 一些可以以后完成的事情

    • 暂时不推荐使用 NOTE 标记

测试

  • feeluown 包相关代码都应该添加相应测试。

  • GUI 改动优先运行 focused GUI/library 测试。如果本地环境中完整 Qt/mpv pytest 不稳定，应在 PR 说明中明确记录。

错误处理

  • Qt 中同步调用资源提供方接口时，都应该处理 Exception 异常，否则应用可能会 crash。

  • 避免用宽泛的 fallback 分支隐藏失败。如果输入契约不符合预期，应通过明确的 类型或结构检查尽早失败。

特殊风格

  • 标记了 alpha 的函数和类，它们的设计都是不确定的，外部应该尽少依赖。

类

  • Qt Widget 的子类的 UI 相关设置初始化应该放在 _setup_ui 函数中。

  • 信号的 slot 方法应该设为 protected 方法。

  • 类的 public 方法放在类的前面，protected 和 private 方法放在类的最后面， _setup_ui 函数除外。

  • QWidget 子类最好不要有 async 方法，因为目前无法很好的为它编写相关单元测试。

UI 设计

  • 设计 UI 时要考虑 Linux、Windows、macOS 的兼容性。颜色应尽量来自系统 调色板，比如 QPalette 的 Window、Base、Text、 WindowText、Highlight 等角色，而不是硬编码某一种颜色。

运行时调试

  • 可以用 fuo exec 连接正在运行的应用，执行 Python 代码来调试界面状态、 构造测试场景或读取对象属性。启动应用时不要使用 -ns，因为它表示 no-server，fuo exec 将无法连接到应用。

  • fuo exec 支持从 stdin 接收多行 Python 代码。调试复杂流程时优先使用 这种方式，避免在 shell 参数中处理繁琐的引号和转义。示例:

    # 在 tmux 中启动 GUI，并打开 server
uv run fuo -vv

# 在另一个 shell 中注入多行 Python 代码
uv run fuo exec <<'EOF'
print(type(app).__name__)
print(app.ui)
EOF

工程经验

  • API 命名应优先表达语义，而不是绑定某个调用场景。例如 show_cover_with_source(artwork, source, uid) 比编码某个具体 caller 上下文的名字更清晰。

  • 封面和图片加载应保持清晰边界：数据/适配层负责把 (url, source) 转换为 Media，widget 层尽量直接消费 Media。

  • 删除 helper 函数前，先用 rg 明确检查使用点。如果它仍被多个 GUI 路径共享， 应保留这个 helper。

  • 通过 gh 创建或更新 PR 描述时，优先使用 --body-file，或使用 GraphQL updatePullRequest 并从文件读取正文；避免在命令行里内联转义 \n， 否则 PR 描述可能出现字面量 \n。