lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linting and Code Quality Skill

代码检查与代码质量技能

This skill helps you efficiently validate and format code using the project's comprehensive linting infrastructure.

本技能可借助项目全面的代码检查基础设施，帮助你高效验证和格式化代码。

When to Use This Skill

何时使用本技能

Use this skill when you:

Edit a file and want to format it before committing
Need to validate code style, types, or security
Want to check for spelling errors or documentation issues
Need to validate test infrastructure (suitespec, log messages)
Want to run comprehensive quality checks before pushing

当你遇到以下场景时，可使用本技能：

编辑文件后，希望在提交前进行格式化
需要验证代码风格、类型或安全性
想要检查拼写错误或文档问题
需要验证测试基础设施（suitespec、日志消息）
希望在推送代码前运行全面的质量检查

Key Principles

核心原则

Always format after editing - Use
```
hatch run lint:fmt -- <file>
```
immediately after code changes
Run comprehensive checks before committing - Use
```
hatch run lint:checks
```
before pushing
Target specific files - Use
```
-- <file>
```
syntax to validate only what you changed, not the entire codebase
Fix auto-fixable issues - Use
```
fmt
```
instead of manually fixing style issues
Type check after adding types - Use
```
hatch run lint:typing -- <file>
```
after adding type annotations

编辑后立即格式化 - 代码修改完成后，立即使用
```
hatch run lint:fmt -- <file>
```
命令
提交前运行全面检查 - 推送代码前使用
```
hatch run lint:checks
```
命令
针对特定文件 - 使用
```
-- <file>
```
语法仅验证你修改的内容，而非整个代码库
修复可自动修复的问题 - 使用
```
fmt
```
命令而非手动修复风格问题
添加类型后进行类型检查 - 添加类型注解后，使用
```
hatch run lint:typing -- <file>
```
命令

Quick Start

快速开始

Run all checks (broad validation):

bash

hatch run lint:checks

Format and validate a specific file:

bash

hatch run lint:fmt -- path/to/file.py

Check types on a specific file:

bash

hatch run lint:typing -- path/to/file.py

运行全部检查（全面验证）：

bash

hatch run lint:checks

格式化并验证特定文件：

bash

hatch run lint:fmt -- path/to/file.py

检查特定文件的类型：

bash

hatch run lint:typing -- path/to/file.py

Available Lint Scripts

可用的Lint脚本

Code Formatting

代码格式化

fmt

- Format code (recommended for most edits)

fmt

- 格式化代码（大多数编辑场景推荐使用）

Formats and validates code style using Ruff.

Usage:

bash

undefined

使用Ruff格式化并验证代码风格。

使用方式：

bash

undefined

Format entire codebase

格式化整个代码库

hatch run lint:fmt

Format specific files

格式化特定文件

hatch run lint:fmt -- ddtrace/tracer.py tests/test_tracer.py

Format specific directory

格式化特定目录

hatch run lint:fmt -- ddtrace/contrib/flask/


**What it does:**
1. Runs the Ruff formatter
2. Runs Ruff with --fix to auto-fix issues
3. Re-validates with style checks

**When to use:** After making code changes to automatically format and fix style issues.

hatch run lint:fmt -- ddtrace/contrib/flask/


**功能说明：**
1. 运行Ruff格式化工具
2. 使用Ruff的--fix参数自动修复问题
3. 重新执行风格检查进行验证

**适用场景：** 代码修改完成后，自动格式化并修复风格问题。

fmt-snapshots

- Format snapshot files

fmt-snapshots

- 格式化快照文件

Formats snapshot test files used in snapshot-based testing.

Usage:

bash

hatch run lint:fmt-snapshots -- tests/snapshots/

When to use: After snapshot test updates or when snapshot files need reformatting.

格式化基于快照测试的快照测试文件。

使用方式：

bash

hatch run lint:fmt-snapshots -- tests/snapshots/

适用场景： 更新快照测试后，或快照文件需要重新格式化时。

Style Checking

风格检查

style

- Check all style issues (no auto-fix)

style

- 检查所有风格问题（无自动修复）

Validates code style without automatically fixing issues.

Usage:

bash

undefined

验证代码风格，但不自动修复问题。

使用方式：

bash

undefined

Check entire codebase

检查整个代码库

hatch run lint:style

Check specific files

检查特定文件

hatch run lint:style -- ddtrace/


**What it validates:**
- Ruff formatting
- Ruff linting rules
- Cython linting
- C code formatting
- CMake formatting

**When to use:** To verify style compliance before committing without auto-fixes.

hatch run lint:style -- ddtrace/


**验证内容：**
- Ruff格式化
- Ruff检查规则
- Cython代码检查
- C代码格式化
- CMake格式化

**适用场景：** 提交前验证代码风格合规性，且不需要自动修复。

format_check

- Check formatting

format_check

- 检查格式化情况

Validates Python code formatting with

ruff format

(no auto-fix).

Usage:

bash

hatch run lint:format_check -- ddtrace/tracer.py

When to use: Quick check of Python formatting before committing.

使用

ruff format

验证Python代码格式化（无自动修复）。

使用方式：

bash

hatch run lint:format_check -- ddtrace/tracer.py

适用场景： 提交前快速检查Python代码格式化情况。

Type Checking

类型检查

typing

- Type check with mypy

typing

- 使用mypy进行类型检查

Validates Python type hints and catches type-related errors.

Usage:

bash

undefined

验证Python类型提示，捕获类型相关错误。

使用方式：

bash

undefined

Check all types

检查所有类型

hatch run lint:typing

Check specific files (mypy path format)

检查特定文件（使用mypy路径格式）

hatch run lint:typing -- ddtrace/tracer.py


**When to use:** After adding type hints or modifying functions with type annotations.

hatch run lint:typing -- ddtrace/tracer.py


**适用场景：** 添加类型提示或修改带类型注解的函数后。

Security Checks

安全检查

security

- Security audit with Bandit

security

- 使用Bandit进行安全审计

Scans code for common security issues and vulnerabilities.

Usage:

bash

undefined

扫描代码中的常见安全问题与漏洞。

使用方式：

bash

undefined

Scan entire codebase

扫描整个代码库

hatch run lint:security

Scan specific directory

扫描特定目录

hatch run lint:security -- -r ddtrace/contrib/


**When to use:** Before committing code that handles user input, credentials, or sensitive operations.

hatch run lint:security -- -r ddtrace/contrib/


**适用场景：** 提交处理用户输入、凭证或敏感操作的代码前。

Spelling and Documentation

拼写与文档检查

spelling

- Check spelling

spelling

- 检查拼写

Validates spelling in documentation, comments, and docstrings.

Usage:

bash

undefined

验证文档、注释和文档字符串中的拼写。

使用方式：

bash

undefined

Check all spelling

检查所有拼写

hatch run lint:spelling

Check specific files

检查特定文件

hatch run lint:spelling -- docs/ releasenotes/


**When to use:** Before committing documentation or user-facing text.

hatch run lint:spelling -- docs/ releasenotes/


**适用场景：** 提交文档或面向用户的文本前。

Test Infrastructure

测试基础设施检查

riot

- Validate riotfile

riot

- 验证riotfile

Doctests the riotfile to ensure test venv definitions are valid.

Usage:

bash

hatch run lint:riot

When to use: After modifying

riotfile.py

to validate syntax and doctest examples.

对riotfile进行文档测试，确保测试虚拟环境定义有效。

使用方式：

bash

hatch run lint:riot

适用场景： 修改

riotfile.py

后，验证语法和文档测试示例。

suitespec-check

- Validate test suite specifications

suitespec-check

- 验证测试套件规范

Checks that test suite patterns in

tests/suitespec.yml

cover all test files.

Usage:

bash

hatch run lint:suitespec-check

When to use: After adding new test files or modifying suite specifications.

检查

tests/suitespec.yml

中的测试套件模式是否覆盖所有测试文件。

使用方式：

bash

hatch run lint:suitespec-check

适用场景： 添加新测试文件或修改套件规范后。

error-log-check

- Validate error log messages

error-log-check

- 验证错误日志消息

Ensures error log messages follow project conventions.

Usage:

bash

hatch run lint:error-log-check

When to use: After adding new error logging statements.

确保错误日志消息符合项目约定。

使用方式：

bash

hatch run lint:error-log-check

适用场景： 添加新的错误日志语句后。

Code Analysis

代码分析

sg

- Static analysis with ast-grep

sg

- 使用ast-grep进行静态分析

Performs static code analysis using ast-grep patterns.

Usage:

bash

undefined

使用ast-grep模式执行静态代码分析。

使用方式：

bash

undefined

Scan all files

扫描所有文件

hatch run lint:sg

Scan specific directory

扫描特定目录

hatch run lint:sg -- ddtrace/


**When to use:** To find code patterns that may need refactoring or optimization.

hatch run lint:sg -- ddtrace/


**适用场景：** 查找可能需要重构或优化的代码模式。

sg-test

- Test ast-grep rules

sg-test

- 测试ast-grep规则

Validates ast-grep rule definitions.

Usage:

bash

hatch run lint:sg-test

When to use: After modifying ast-grep rules or patterns.

验证ast-grep规则定义。

使用方式：

bash

hatch run lint:sg-test

适用场景： 修改ast-grep规则或模式后。

C/CMake Formatting

C/CMake格式化检查

cformat_check

- Check C code formatting

cformat_check

- 检查C代码格式化

Validates C code formatting.

Usage:

bash

hatch run lint:cformat_check

When to use: After modifying C extension code.

验证C代码格式化情况。

使用方式：

bash

hatch run lint:cformat_check

适用场景： 修改C扩展代码后。

cmakeformat_check

- Check CMake formatting

cmakeformat_check

- 检查CMake格式化

Validates CMake file formatting.

Usage:

bash

hatch run lint:cmakeformat_check

When to use: After modifying CMakeLists.txt or other CMake files.

验证CMake文件格式化情况。

使用方式：

bash

hatch run lint:cmakeformat_check

适用场景： 修改CMakeLists.txt或其他CMake文件后。

Common Workflows

常见工作流

Workflow 1: Quick File Format and Check

工作流1：快速格式化与检查文件

After editing a Python file, format and validate it:

bash

undefined

编辑Python文件后，格式化并验证：

bash

undefined

Edit the file...

编辑文件...

Then run:

然后运行：

hatch run lint:fmt -- path/to/edited/file.py

undefined

hatch run lint:fmt -- path/to/edited/file.py

undefined

Workflow 2: Type Check After Adding Types

工作流2：添加类型后的类型检查

After adding type hints:

bash

hatch run lint:typing -- ddtrace/contrib/flask/patch.py

添加类型提示后：

bash

hatch run lint:typing -- ddtrace/contrib/flask/patch.py

Workflow 3: Full Validation Before Commit

工作流3：提交前的全面验证

Run all checks before creating a commit:

bash

hatch run lint:checks

This runs:

style checks
typing checks
spelling checks
riot validation
security checks
suitespec validation
error log validation
ast-grep analysis

创建提交前运行全部检查：

bash

hatch run lint:checks

此命令会运行：

风格检查
类型检查
拼写检查
riot验证
安全检查
suitespec验证
错误日志验证
ast-grep分析

Workflow 4: Security Review

工作流4：安全审查

Before committing code handling sensitive operations:

bash

hatch run lint:security -- -r ddtrace/contrib/

提交处理敏感操作的代码前：

bash

hatch run lint:security -- -r ddtrace/contrib/

Workflow 5: Documentation Review

工作流5：文档审查

After writing documentation or docstrings:

bash

hatch run lint:spelling -- docs/ ddtrace/

编写文档或文档字符串后：

bash

hatch run lint:spelling -- docs/ ddtrace/

Best Practices

最佳实践

DO ✅

建议✅

Format files immediately after editing: Use
```
hatch run lint:fmt -- <file>
```
to auto-fix style issues
Run
lint:checks
before pushing: Ensures all quality gates pass
Target specific files: Use
```
-- <file>
```
syntax to validate only what you changed
Check types early: Run
```
lint:typing
```
after adding type annotations
Read error messages: Understand what lint failures mean before fixing

编辑后立即格式化文件：使用
```
hatch run lint:fmt -- <file>
```
自动修复风格问题
推送前运行
lint:checks
：确保所有质量关卡都能通过
针对特定文件：使用
```
-- <file>
```
语法仅验证你修改的内容
尽早检查类型：添加类型注解后运行
```
lint:typing
```
阅读错误消息：在修复前理解Lint失败的原因

DON'T ❌

不建议❌

Ignore lint failures: They indicate potential bugs or style issues
Manually fix issues that auto-fix can handle: Use
```
fmt
```
instead
Commit without running lint:checks: Let automation catch issues before push
Run lint:checks every time for small changes: Use targeted commands during development

忽略Lint失败：失败提示可能意味着潜在的bug或风格问题
手动修复可自动修复的问题：使用
```
fmt
```
命令代替手动操作
未运行
lint:checks
就提交：让自动化工具在推送前发现问题
小改动时每次都运行
lint:checks
：开发过程中使用定向命令

Passing Arguments

传递参数

All lint commands support passing arguments with

--

syntax:

bash

undefined

所有Lint命令都支持使用

--

语法传递参数：

bash

undefined

Basic format

基本格式

hatch run lint:<script> -- <args>

Examples:

示例：

hatch run lint:fmt -- ddtrace/tracer.py # Format specific file hatch run lint:typing -- ddtrace/ # Type check directory hatch run lint:security -- -r ddtrace/contrib/ # Security scan with args hatch run lint:spelling -- docs/ releasenotes/ # Spelling check specific paths

undefined

hatch run lint:fmt -- ddtrace/tracer.py # 格式化特定文件 hatch run lint:typing -- ddtrace/ # 检查目录类型 hatch run lint:security -- -r ddtrace/contrib/ # 带参数的安全扫描 hatch run lint:spelling -- docs/ releasenotes/ # 检查特定路径的拼写

undefined

Troubleshooting

故障排除

Formatting keeps failing

格式化持续失败

Ensure you've run

hatch run lint:fmt

to auto-fix style issues first:

bash

hatch run lint:fmt -- <file>
hatch run lint:style -- <file>  # Should now pass

确保先运行

hatch run lint:fmt

自动修复风格问题：

bash

hatch run lint:fmt -- <file>
hatch run lint:style -- <file>  # 现在应该可以通过

Type errors after editing

编辑后出现类型错误

Make sure type hints are correct and all imports are available:

bash

hatch run lint:typing -- <file>

确保类型提示正确，且所有导入都可用：

bash

hatch run lint:typing -- <file>

Lint command not found

找不到Lint命令

Ensure you're running from the project root:

bash

cd /path/to/dd-trace-py
hatch run lint:checks

确保你在项目根目录运行命令：

bash

cd /path/to/dd-trace-py
hatch run lint:checks

Too many errors to fix manually

错误太多无法手动修复

Use

fmt

to auto-fix most issues:

bash

hatch run lint:fmt -- .

使用

fmt

命令自动修复大多数问题：

bash

hatch run lint:fmt -- .