ragflow/.agents/rules/named.md

Go Naming Best Practices

1. Package Naming

• All lowercase, no underscores: package user, not package userService or package user_service
• Short and meaningful: package http, package json, package dao
• Avoid plurals: package user not package users
• Avoid generic names: Avoid package util, package common, package base

// Recommended
package user
package handler
package service

// Not recommended
package UserService
package user_service
package utils

2. File Naming

• All lowercase, underscore separated: user_handler.go, user_service.go
• Test files: user_handler_test.go
• Platform-specific: user_linux.go, user_windows.go

user/
├── user_handler.go
├── user_service.go
├── user_dao.go
└── user_test.go

3. Directory Naming

• All lowercase, no underscores or hyphens: internal/, pkg/, cmd/
• Short and descriptive: handler/, service/, dao/

project/
├── cmd/                    # Main entry point
│   └── server_main.go
├── internal/               # Private code
│   ├── handler/
│   ├── service/
│   ├── dao/
│   ├── model/
│   └── middleware/
├── pkg/                    # Public code
└── api/                    # API definitions

4. Interface Naming

• Single-method interfaces end with "-er": Reader, Writer, Handler
• Verb form: Reader, Executor, Validator

// Recommended
type Reader interface {
    Read(p []byte) (n int, err error)
}

type UserService interface {
    Register(req *RegisterRequest) (*User, error)
    Login(req *LoginRequest) (*User, error)
}

// Not recommended
type UserInterface interface {}
type IUserService interface {}

5. Struct Naming

• CamelCase: UserService, UserHandler
• Avoid redundant prefixes: User not UserModel

// Recommended
type UserService struct {}
type UserHandler struct {}
type RegisterRequest struct {}

// Not recommended
type user_service struct {}
type SUserService struct {}
type UserModel struct {}

6. Method/Function Naming

• CamelCase
• Start with verb: GetUser, CreateUser, DeleteUser
• Boolean returns use Is/Has/Can prefix: IsValid, HasPermission

// Recommended
func (s *UserService) Register(req *RegisterRequest) (*User, error)
func (s *UserService) GetUserByID(id uint) (*User, error)
func (s *UserService) IsEmailExists(email string) bool

// Not recommended
func (s *UserService) register_user()
func (s *UserService) get_user_by_id()
func (s *UserService) CheckEmailExists() // Should use Is/Has

7. Constant Naming

• CamelCase: const MaxRetryCount = 3
• Enum constants: const StatusActive = "active"

// Recommended
const (
    StatusActive   = "1"
    StatusInactive = "0"
    MaxRetryCount  = 3
)

// Not recommended
const (
    STATUS_ACTIVE = "1"  // Not all uppercase
    status_active = "1"  // Not all lowercase
)

8. Error Variable Naming

• Start with "Err": ErrNotFound, ErrInvalidInput

// Recommended
var (
    ErrNotFound      = errors.New("not found")
    ErrInvalidInput  = errors.New("invalid input")
    ErrUnauthorized  = errors.New("unauthorized")
)

9. Acronyms Keep Consistent Case

// Recommended
type HTTPHandler struct {}
var URL string
func GetHTTPClient() {}
func ParseJSON() {}

// Not recommended
type HttpHandler struct {}
var Url string
func GetHttpClient() {}

10. Project Structure Naming

project-name/
├── cmd/                    # Main programs
│   └── app_name/
│       └── main.go
├── internal/               # Private code
│   ├── handler/           # HTTP handlers
│   ├── service/           # Business logic
│   ├── repository/        # Data access
│   ├── model/             # Data models
│   └── config/            # Configuration
├── pkg/                    # Public code
├── api/                    # API definitions
├── configs/               # Config files
├── scripts/               # Scripts
├── docs/                  # Documentation
├── go.mod
└── go.sum

Summary Table

Type	Rule	Example
Package	All lowercase, no underscores	package user
File	All lowercase, underscore separated	user_service.go
Directory	All lowercase, no separators	internal/handler/
Struct	CamelCase, capitalized first letter	UserService
Interface	CamelCase, -er suffix	Reader, Writer
Method	CamelCase, verb prefix	GetUserByID
Constant	CamelCase	MaxRetryCount
Error Variable	Err prefix	ErrNotFound