让 Cursor 更加聪明

摘要

为了让 Cursor 更加“聪明”，即提高 Codebase Indexing 其索引和分析代码的效率、准确性和语义理解能力，开发者可以通过以下方式优化代码编写和项目结构。这些方法不仅有助于提升索引的效果，还能改善整体代码质量和可维护性。

1. 遵循清晰的代码规范

命名规范： 使用有意义的变量名、函数名和类名，避免模糊或过于简短的命名（如 x、temp）。清晰的命名可以帮助索引工具更好地理解代码意图。

# 不推荐
def calc(a, b):
  return a + b

# 推荐
def calculate_sum(value1, value2):
  return value1 + value2

注释与文档： 为关键逻辑添加注释，并使用标准的文档格式（如 JSDoc、Docstring）描述函数、类和模块的功能。

def calculate_area(radius):
    """
    Calculate the area of a circle given its radius.

    Args:
        radius (float): The radius of the circle.

    Returns:
        float: The area of the circle.
    """
    return 3.14159 * radius ** 2

2. 模块化设计

拆分功能模块： 将代码按功能划分为多个模块或文件，避免单个文件过大或功能过于复杂。模块化的代码更容易被索引工具解析和导航。

# 不推荐：所有功能都写在一个文件中
# main.py
def process_data(data):
    ...

def save_to_database(data):
    ...

# 推荐：按功能划分模块
# data_processor.py
def process_data(data):
    ...

# database_handler.py
def save_to_database(data):
    ...

3. 使用类型注解

显式类型声明： 为变量、函数参数和返回值添加类型注解，帮助索引工具理解代码的语义。

# 不推荐
def add(a, b):
    return a + b

# 推荐
def add(a: int, b: int) -> int:
    return a + b

类型注解不仅能提升索引工具的语义理解能力，还能在开发过程中提供更好的智能提示。

4. 避免动态特性

减少动态行为： 尽量避免使用动态语言特性（如动态属性、动态导入），因为这些特性会增加静态分析的难度。

# 不推荐：动态属性难以解析
class MyClass:
    def __init__(self):
        self.dynamic_attr = "value"

# 推荐：明确属性定义
class MyClass:
    def __init__(self):
        self.static_attr: str = "value"

5. 提供明确的依赖关系

显式导入： 确保所有依赖项都通过显式的 import 语句引入，避免隐式依赖或动态加载。

# 不推荐：动态导入难以解析
module = __import__("some_module")

# 推荐：显式导入
import some_module

避免循环依赖： 循环依赖会导致索引工具难以正确解析模块之间的关系。

6. 使用标准化的项目结构

遵循约定： 采用社区推荐的项目结构（如 Python 的 src/ 目录结构、JavaScript 的 src/ 和 tests/ 分离），便于索引工具识别不同类型的文件。

my_project/
├── src/
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── test_module1.py
│   └── test_module2.py
└── README.md

7. 添加配置文件

支持工具识别： 为项目添加配置文件（如 .eslintrc、pyproject.toml），帮助索引工具了解项目的语言版本、依赖管理和编码规范。

# pyproject.toml 示例
[tool.black]
line-length = 88
target-version = ['py38']

8. 测试代码分离

独立测试文件： 将测试代码与生产代码分离，并使用统一的命名规则（如 test_*.py 或 *.test.js），方便索引工具区分两者。

# 生产代码
# src/calculator.py
def add(a, b):
    return a + b

# 测试代码
# tests/test_calculator.py
import unittest
from src.calculator import add

class TestCalculator(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(1, 2), 3)

9. 定期清理无用代码

移除冗余代码： 定期删除未使用的函数、变量和文件，减少索引工具的工作量。 避免重复逻辑： 通过重构消除重复代码，使索引结果更加简洁和高效。

10. 利用工具生成元信息

生成符号表或映射文件： 某些语言或框架支持生成符号表（如 TypeScript 的 .d.ts 文件），可以显著提升索引工具的语义理解能力。

# 示例：生成 TypeScript 声明文件
tsc --declaration

.小蟹蟹蟹蟹

摘要