Contents
Remove obsolete or incorrect comments.
（古いまたは誤ったコメントを削除する）
解説
コードが変更されたにもかかわらずコメントが更新されないと、コメントが嘘の情報源となり、開発者を誤った方向に導きます。古いコメントは、コードの理解を助けるどころか混乱を招き、バグの原因となります。コードを変更する際は、関連するコメントも同時に更新するか、不要になったコメントは削除すべきです。正確なコメントのみが価値を持ちます。
具体例
// 悪い例（古いコメントが残っている）
type UserService struct {
db Database
}
// CreateUser creates a new user and sends a welcome email
// この関数はemailとpasswordを受け取ります
func (s *UserService) CreateUser(name string) error {
// 実際にはnameしか受け取っていない
// メール送信機能も削除済み
return s.db.Insert(name)
}
// ValidatePassword checks if password meets requirements
// パスワードは8文字以上必要です
func ValidatePassword(password string) bool {
// 実際には12文字以上に変更された
return len(password) >= 12
}
// 良い例（正確なコメント）
type UserService struct {
db Database
}
// CreateUser creates a new user with the given name
func (s *UserService) CreateUser(name string) error {
return s.db.Insert(name)
}
// ValidatePassword checks if password is at least 12 characters
func ValidatePassword(password string) bool {
return len(password) >= 12
}
参考リンク
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) {
// ...
}
参考リンク
Contents
Do not write comments that merely restate the code (e.g., int a // declare integer a).
（コードを単に言い換えるだけのコメントを書かない（例：int a // 整数aを宣言））
解説
コードをそのまま言い換えただけのコメントは、情報を追加せず、コードのノイズとなります。コメントは、コードから読み取れない意図や理由、背景を説明するべきです。自明な内容をコメントで繰り返すことは時間の無駄であり、コメントのメンテナンスコストを不必要に増加させます。意味のあるコメントのみを書くことで、コードの可読性が向上します。
具体例
// 悪い例（自明な内容の繰り返し）
// increment i by 1
i++
// create a new user
user := User{}
// check if name is empty
if name == "" {
return errors.New("name is required")
}
// loop through all items
for _, item := range items {
// process item
process(item)
}
// 良い例（意図や理由を説明）
// ユーザーIDは1から開始（0は予約済み）
i := 1
// デフォルト値で初期化（後でAPIレスポンスで上書き）
user := User{Status: "pending"}
// 空の名前は無効（ビジネスルール）
if name == "" {
return errors.New("name is required")
}
// すべてのアイテムに対して在庫を減算
// エラーが発生してもロールバックしない（べき等性保証）
for _, item := range items {
process(item)
}
// コメント不要な例（コード自体が明確）
func calculateTax(price float64) float64 {
return price * 0.1
}
if user.IsActive() {
sendNotification(user)
}
参考リンク
