---
name: ascii-text-style
version: 1.0.0
description: |
  Enforce personal source-text conventions when writing or reviewing comments,
  log and debug strings, and commit messages: ASCII characters only (no em
  dashes, no unicode arrows or symbols), concise comments that skip the obvious,
  and restrained ticket-name mentions. Use when writing code comments, logging
  strings, error messages, or commit text, or when the user asks to clean up
  non-ascii characters or over-commented code.
license: MIT
compatibility: claude-code cursor codex gemini-cli opencode
---

# ASCII Text Style

Conventions for text written inside source code: comments, debug and log strings,
and commit messages. The goal is text that stays plain ASCII, stays short, and
does not repeat what the code already says.

## Your Task

When you write or review comments, log strings, error strings, or commit text:

1. Use ASCII characters only.
2. Keep comments concise, and skip comments the code does not need.
3. Mention ticket names only when they add context a reader would want.

Apply the same rules whether you are writing new text or editing existing text.

## Rule 1: ASCII characters only

Never use non-ASCII characters in comments or logging strings. Replace common
non-ASCII characters with ASCII equivalents:

| Do not write | Write instead |
|---|---|
| `—` `–` (em dash, en dash) | hyphen (`-`) |
| `→` (right arrow) | `->` |
| `←` (left arrow) | `<-` |
| `“` `”` `‘` `’` (curly quotes) | straight quotes (`'` and `"`) |
| `…` (ellipsis) | three periods (`...`) |
| `×` (multiplication sign) | `x` or `*` |
| non-breaking space | a normal space |

This applies to comments and to logging strings. Use a non-ASCII character only
when the user explicitly asks for it (for example, when the string is
user-facing content that needs a specific glyph).

The examples below intentionally contain real non-ASCII characters in each
"Before" line. Showing the actual character is what the rule needs; if you
replace it with its ASCII form the example teaches nothing. This is the
"explicitly asks for it" exception: the content demands the glyph.

**Before:** `// retry → fallback → give up`
**After:** `// retry -> fallback -> give up`

**Before:** `log.Info("cache miss — fetching from origin")`
**After:** `log.Info("cache miss - fetching from origin")`

**Before:** `// clamp to ±5% of target`
**After:** `// clamp to +/- 5% of target`

## Rule 2: Concise comments

Use enough punctuation to be clear, and no more. Keep comments short.

Do not write a comment when the code explains itself. When you are unsure whether
a comment is needed, leave it out. A missing comment is easy to add later; a
comment that restates the code is noise.

Write comments for the parts a reader cannot get from the code: a non-obvious
constraint, a reason for an unusual choice, or a warning about a side effect.

**Delete this kind of comment:**

```go
// increment i
i++

// return the result
return result
```

**Keep this kind of comment:**

```go
// The vendor API rejects batches over 500, so we chunk here.
for _, batch := range chunk(items, 500) {
```

## Rule 3: Restrained ticket names

Do not add a ticket name to a comment by default. Add one only when the comment
describes behavior that is unintuitive and a reader would want the extra context
that the ticket provides.

**Skip the ticket:**

```go
// Round up to the next whole cent.
total = roundUpCents(total)
```

**Include the ticket, because the behavior is surprising:**

```go
// We keep the stale value for one extra cycle on purpose; removing it
// caused the flapping in JIRA-1234.
return cached
```

## Self-Check

Before you deliver code with comments or log strings:

1. Scan every comment and string literal for non-ASCII characters. Replace each
   one with its ASCII equivalent. The only exception is text that must show the
   character itself, such as a rule or example about that character.
2. Read each comment and ask whether the code already says it. Delete the ones
   that do.
3. Check each ticket-name mention. Remove it unless the comment describes
   unintuitive behavior.