Code Comment Guidelines

Core Philosophy

The best comment is the one you didn't need to write.

Self-documenting code reduces maintenance burden and prevents comment drift. Studies show clear naming and structure can reduce onboarding time by up to 30%.

Writing Style Guidelines

Tone: Be direct, practical, and clear. Write in a natural and relaxed tone. Be approachable and down-to-earth with some personality, but light on the slang and excessive casual terms.

Avoid: