Chinese Copywriting Guidelines: Formatting Rules for Code Comments, README, and Documentation

The article begins with a humorous anecdote about spacing between Chinese and English, then explains that code comments, README.md, and other documentation often mix languages and need consistent formatting.

Chinese Copywriting Guidelines Overview

It references the chinese-copywriting-guidelines project, which aims to unify Chinese documentation style, reduce communication friction, and improve document aesthetics.

Spacing Rules

Insert a space between Chinese and English characters.

Insert a space between Chinese characters and numbers.

Insert a space between numbers and units (e.g., "10 Gbps").

Do not add spaces before full‑width punctuation.

Examples of correct and incorrect usage are provided for each rule.

Punctuation and Typography

Use full‑width Chinese punctuation, avoid repeated punctuation marks, and keep proper half‑width symbols for English text, numbers, and technical terms.

Proper Naming and Capitalization

Technical terms and product names should follow correct case (e.g., "GitHub", "HTML", "JavaScript") and avoid non‑standard abbreviations.

Controversial Cases

Some rules have exceptions, such as product names like "豆瓣FM" or when quoting English titles, where the original formatting should be preserved.

Tools for Enforcing the Guidelines

CLI Tool: autocorrect

Installation is simple via curl -sSL https://git.io/JcGER | sh . The tool can lint ( --lint ) and automatically fix ( --fix ) spacing issues in plain text files.

# Install
$ curl -sSL https://git.io/JcGER | sh
# Lint a file
$ autocorrect --lint test.txt
# Fix a file
$ autocorrect --fix test.txt

Special terms can be added to a .autocorrectrc configuration to prevent unwanted spacing.

Language Libraries

Libraries exist for many languages; the article demonstrates the Go library autocorrect-go with sample code that formats mixed Chinese/English strings correctly.

package main
import (
    "fmt"
    "github.com/longbridgeapp/autocorrect"
)
func main() {
    fmt.Println(autocorrect.Format("长桥LongBridge App下载"))
    // => "长桥 LongBridge App 下载"
}

IDE Plugins

For GoLand users, an AutoCorrect plugin is available, providing right‑click formatting and customizable shortcuts.

Conclusion

The Chinese copywriting guidelines provide a practical reference for consistent documentation, especially handling mixed Chinese‑English text, spacing, punctuation, and proper naming. While no rule covers every edge case, tools like autocorrect help automate compliance, and teams can adapt the guidelines to their own workflows.