各関数の目的を1行コメントで要約する
Contents
Write a one-line comment summarizing the purpose of each function. Argument explanations are unnecessary except in special cases. （各関数の目的を要約する1行コメントを書く。引数の説明は特別な場合を除いて不要）
解説
関数の目的を簡潔に説明するコメントは、コードの理解を助ける重要な要素です。1行のコメントで「何をする関数か」を明確にすることで、コードレビューや保守作業が効率化されます。ただし、引数や戻り値の詳細な説明は、型や名前から自明な場合は不要です。コメントは実装の詳細ではなく、関数の意図や目的を伝えることに焦点を当てるべきです。
具体例
// 悪い例（コメントなし、または冗長）
func ProcessOrder(order Order) error {
// この関数はOrderを受け取り、それを処理し、エラーがあればエラーを返します
// 引数: order - 処理するOrder型の変数
// 戻り値: error - エラーがあればerror、なければnil
// ...
}
// 良い例
// ProcessOrder は注文を検証して保存し、確認メールを送信する
func ProcessOrder(order Order) error {
// ...
}
// CalculateTax は商品価格に対する消費税額を計算する
func CalculateTax(price float64) float64 {
return price * 0.1
}
// FetchActiveUsers はアクティブなユーザー一覧をデータベースから取得する
func FetchActiveUsers() ([]User, error) {
// ...
}
// GenerateInvoicePDF は注文データからPDF形式の請求書を生成する
// pdfOptions: マージン、フォントサイズなど細かい制御が必要な場合のみコメント
func GenerateInvoicePDF(order Order, pdfOptions PDFOptions) ([]byte, error) {
// ...
}
参考リンク
各関数の目的を1行コメントで要約する https://www.tricrow.com/core/coding-standard/function-comment.html
