AI駆動開発工房

命名規則

3 件の記事

略語ではなく完全な単語を使う

Contents

Use full words rather than abbreviations (e.g., compensatingTransaction instead of ct). Commonly accepted abbreviations like db are fine. （略語ではなく完全な単語を使う（例：ctではなくcompensatingTransaction）。dbのように一般的に受け入れられている略語は問題ない）

解説

略語は、書いた本人以外には意味が不明確で、コードの理解を妨げます。完全な単語を使用することで、コードの意図が明確になり、新しいメンバーでも容易に理解できます。現代のエディタには自動補完機能があるため、長い名前でも入力の手間は問題になりません。ただし、広く認知されている略語（例：db、api、html、url）は使用しても問題ありません。

具体例

// 悪い例（独自の略語を使用）
func ProcUsrData(usr *Usr) error {
    // usr, Procは何の略か不明
    res := CalcTtl(usr.Itms)
    // res, Ttl, Itmsは何の略か不明

    if err := SaveToDb(res); err != nil {
        return err
    }

    return nil
}

type Usr struct {
    Nm   string  // Nmは何の略？
    Em   string  // Emは何の略？
    Ph   string  // Phは何の略？
    Itms []Item
}

func CalcTtl(itms []Item) float64 {
    ttl := 0.0
    for _, itm := range itms {
        ttl += itm.Prc
    }
    return ttl
}

// 良い例（完全な単語を使用）
func ProcessUserData(user *User) error {
    total := CalculateTotal(user.Items)

    if err := SaveToDatabase(total); err != nil {
        return err
    }

    return nil
}

type User struct {
    Name  string
    Email string
    Phone string
    Items []Item
}

func CalculateTotal(items []Item) float64 {
    total := 0.0
    for _, item := range items {
        total += item.Price
    }
    return total
}

// 一般的な略語は使用可（良い例）
type UserRepository struct {
    db  *sql.DB     // dbは一般的
    api APIClient   // apiは一般的
}

func FetchFromAPI(url string) ([]byte, error) {
    // url, apiは一般的
    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    return io.ReadAll(resp.Body)
}

func GenerateHTML(data TemplateData) string {
    // htmlは一般的
    return renderTemplate(data)
}

参考リンク

変数と関数には意味のある名前を使う

Contents

Use meaningful names for variables and functions (e.g., good: getUser() / bad: method1()). （変数と関数には意味のある名前を使う（例: 良い getUser() / 悪い method1()））

解説

変数や関数に意味のある名前を付けることは、コードの可読性と保守性を高める基本原則です。名前から目的や役割が明確に伝わることで、他の開発者がコードを理解しやすくなります。抽象的な名前や番号付きの名前は、コードレビューやデバッグ時に混乱を招き、バグの温床となります。MUST項目として、すべての変数と関数に対して例外なく適用されるべきルールです。

具体例

// 悪い例
func method1() User {
    var a = "john@example.com"
    var b = fetchData(a)
    return b
}

// 良い例
func getUser() User {
    userEmail := "john@example.com"
    user := fetchUserByEmail(userEmail)
    return user
}

参考リンク

関数名は動詞または動詞+目的語で命名する

Contents

Name functions with a verb or verb + object. （関数名は動詞または動詞+目的語で命名する）

解説

関数は動作を表すため、動詞で始まる名前が自然で理解しやすくなります。動詞+目的語の形式は、関数が何を行うかを明確に伝え、コードの可読性を向上させます。名詞だけの関数名は、その関数が何をするのか不明確であり、混乱を招きます。一貫した命名規則に従うことで、チーム全体でのコードの理解が容易になります。

具体例

// 悪い例（名詞のみ、または不明瞭）
func User(id string) User {
    // Userは名詞のみで、何をする関数か不明
}

func Data() []byte {
    // 何のデータを取得するのか不明
}

func Process() {
    // 何を処理するのか不明
}

func Order(items []Item) {
    // 注文を作成？取得？
}

// 良い例（動詞+目的語）
func GetUser(id string) User {
    // ユーザーを取得することが明確
}

func FetchUserData() []byte {
    // ユーザーデータを取得することが明確
}

func ProcessOrder(order Order) error {
    // 注文を処理することが明確
}

func CreateOrder(items []Item) (Order, error) {
    // 注文を作成することが明確
}

func ValidateEmail(email string) bool {
    // メールアドレスを検証することが明確
}

func CalculateTotalPrice(items []Item) float64 {
    // 合計金額を計算することが明確
}

func SendNotification(user User, message string) error {
    // 通知を送信することが明確
}

func UpdateUserProfile(userID string, profile Profile) error {
    // ユーザープロフィールを更新することが明確
}

func DeleteExpiredSessions() error {
    // 期限切れセッションを削除することが明確
}

参考リンク