Go Documentation

Writing Principles

Code shows what; comments explain why and when. Every doc comment must add information the reader cannot read directly from the signature.

Anti-patterns to remove on sight:

• Paraphrase comments that start with the name and stop there (// Foo returns a foo.)
• Signature restatement (// Parse parses the input string into T.)
• Marketing vocabulary (seamlessly, robust, enterprise-grade)
• Hedged future claims (easy to extend, for future use)

Package Comments

Every package needs one. Place it in doc.go for non-trivial packages: