Code Citation Format¶

Code Reference Format¶

When referencing existing code from the codebase, use the following format:

```startLine:endLine:filepath
// code content here

### Required Components

1. startLine: The starting line number (required)
2. endLine: The ending line number (required)
3. filepath: The full path to the file (required)

### Format Rules

- No language tags: Do NOT add language tags (like `typescript` or `tsx`) to code references.
- Include actual code: Always include at least 1 line of actual code content.
- Truncation: You may truncate long sections with comments like `// ... more code ...`.
- Clarifying comments: You may add clarifying comments for readability.

### Examples

#### Good: Complete Code Reference

```12:14:app/components/Todo.tsx export const Todo = () => { return

Todo

; };

Good: Truncated Code Reference¶

```23:45:app/utils/api.ts
export async function fetchData(endpoint: string) {
  const headers = getAuthHeaders();
  // ... validation and error handling ...
  return await fetch(endpoint, { headers });
}

#### Bad: Missing Line Numbers

```typescript:app/components/Todo.tsx export const Todo = () => { return

Todo

; };

Bad: Empty Code Block¶

```12:14:app/components/Todo.tsx

## When to Use Code References

- Existing Code: Use code references when showing code that already exists in the codebase.
- Code Reviews: When discussing specific code sections.
- Explanations: When explaining how existing code works.
- Modifications: When showing what needs to be changed.

## When to Use Markdown Code Blocks

Use standard markdown code blocks (with language tag) for:

- New Code: Code that doesn't exist yet in the codebase.
- Proposed Changes: Showing proposed code changes.
- Examples: Standalone code examples not from the codebase.
- Configuration: Configuration files or examples.

### Markdown Code Block Format

```typescript
// Example: New code proposal
export function newFunction() {
  return 'new implementation';
}

Formatting Rules¶

Never Include Line Numbers in Code Content¶

Bad¶

1  for i in range(10):
2      print(i)

Good¶

for i in range(10):
    print(i)

Never Indent Triple Backticks¶

Even when the code block appears in a list or nested context, triple backticks must start at column 0:

Bad¶

- Here's a Python loop:
  ```python
  for i in range(10):
      print(i)

#### Good

Here's a Python loop:

for i in range(10):
    print(i)

## Best Practices

- Use code references for existing code.
- Use markdown blocks for new/proposed code.
- Always include line numbers for references.
- Include enough context to understand the code.
- Keep references focused and relevant.