Python Naming Conventions for Clean, Professional Code (PEP 8 + Real‑World Guide)

Quy tắc Đặt tên trong Python cho Code Sạch và Chuyên nghiệp (PEP 8 + Hướng dẫn Thực tế)

Đối tượng: Kỹ sư AI từ Junior → Senior, đội ngũ data/ML, backend & tooling.
Mục tiêu: Một hướng dẫn thực tiễn, có quan điểm rõ ràng, mở rộng hơn PEP 8—bao gồm Python hiện đại (3.12+), typing, test, FastAPI, dataclass, và các pattern dự án AI phổ biến.

0) Tóm tắt Nhanh (Cheat Sheet)

Thành phần	Quy tắc	Ví dụ	Ghi chú
Package/Folder	snake_case	vector_store/, data_prep/	Không dùng chữ hoa hoặc dấu gạch ngang; folder thành module khi có __init__.py.
Module (file)	snake_case.py	embedding_service.py	Ngắn gọn, có ý nghĩa; ưu tiên danh từ.
Class	PascalCase	EmbeddingService, VectorStore	Danh từ; tránh viết tắt trừ khi chuẩn công nghiệp (VD: HTTPClient).
Exception	PascalCaseError	ValidationError, RateLimitError	Luôn kết thúc bằng Error.
Function/Method	snake_case()	generate_embedding(), to_json()	Động từ; tránh quá dài; rõ ràng.
Variable/Attribute	snake_case	user_id, embedding_dim	Ngắn gọn nhưng đủ nghĩa.
Constant	ALL_CAPS	MAX_TOKENS, DEFAULT_TIMEOUT	Chỉ dùng ở module‑level.
Private (convention)	_dấu_gạch_dưới_đầu	_cache, _normalize()	Ngụ ý: chỉ dùng nội bộ.
Name‑mangled	__2_gạch_dưới	__state	Dùng để tránh override ngoài ý muốn khi kế thừa.
Dunder	__magic__	__init__, __repr__, __call__	Python dành riêng.
TypeVar / NewType	CapWords	T, KT, UserId = NewType(“UserId”, int)	Dùng chữ cái ngắn; alias kiểu dữ liệu thì PascalCase.
Test Modules	test_*.py	test_embedding_service.py	pytest tìm dựa trên prefix test_.
Fixtures	snake_case	client, db_session	Rõ ràng phạm vi: session, module, function.
FastAPI Routers	File snake_case; router = APIRouter()	routes/users.py → /users	API function: get_users(), create_user().
Enum	PascalCase + ALL_CAPS members	class Role(Enum): ADMIN = “admin”	Các thành viên là hằng số.
DataClass / Pydantic	Class PascalCase; field snake_case	class User(BaseModel): user_id: int	JSON nên dễ đọc; alias nếu cần camelCase.
Logging Logger	theo module path	logger = logging.getLogger(__name__)	Không hardcode tên.
Alembic Migration	snake_case + id	20240910_add_user_index.py	Có id + mô tả ngắn.

1) Tại sao đặt tên quan trọng (đặc biệt trong dự án AI)

• Truyền tải ý định: đọc là hiểu ngay thiết kế.
• Giảm bug: phân tách rõ config, service, adapter, domain model.
• Thân thiện công cụ: lint (ruff), type checker (mypy), formatter (black).
• Refactor an toàn: tên tốt giúp giữ contract ổn định.

Nguyên tắc vàng: Đặt tên theo cái nó **là* (danh từ) hoặc cái nó làm (động từ). Tránh mô tả cách nó làm.*

2) Module, Package, và Layout Dự án

• Folder: snake_case → core/, api/, services/.
• Module: file snake_case.py → retrieval_pipeline.py.
• Tránh folder mơ hồ kiểu utils/.

3) Class, Exception, Data Model

• Class: PascalCase → UserService, EmbeddingService.
• Exception: PascalCase + Error → InvalidPromptError.
• Data model: Class PascalCase, field snake_case.

class Document(BaseModel):

    doc_id: str

    content: str

4) Function, Method, Parameter

• Function/method: snake_case → fetch_user().
• Boolean: prefix is_, has_, should_.
• Parameter: đặt rõ ràng, keyword‑only khi cần.

5) Variable, Constant, Scope

• Variable: snake_case → retry_count.
• Constant: ALL_CAPS → MAX_RETRIES.
• _dấu_gạch_dưới: biến nội bộ.
• __mangled: tránh ghi đè khi kế thừa.

6) Typing & Generics

• TypeVar: chữ ngắn → T, KT.
• Alias: PascalCase → JsonDict.
• NewType: PascalCase → UserId = NewType(“UserId”, int).

7) FastAPI, SQLAlchemy, PyTest

• FastAPI: route file routes/users.py; schema UserCreate, UserOut.
• SQLAlchemy: model PascalCase (User), table snake_case (user).
• PyTest: test file test_*.py, test function test_<case>__<expect>().

8) Docstring & Comment

• Viết ở thì mệnh lệnh: “Return…”, “Validate…”.
• Dòng đầu ≤80 ký tự; thêm ví dụ nếu cần.
• Comment giải thích tại sao, không lặp lại code.

9) Lỗi Thường gặp (Anti‑Pattern)

• Tên mơ hồ: data, tmp, stuff.
• Tên quá dài: calculate_similarity_score_for_input_candidate_list_v2().
• Viết tắt khó hiểu: cfg, svc.
• Version trong tên: model_final_v2 → dùng Git/Changelog.

10) Checklist Review Trước khi Merge PR

• Folder/file: snake_case.
• Class/Exception: PascalCase + Error.
• Function/Var: snake_case.
• Constant: ALL_CAPS.
• Không tên mơ hồ (util, misc).
• Logger: logging.getLogger(__name__).
• Test: test_*.py, tên rõ ràng.

11) Kết luận

Đặt tên thống nhất là cách rẻ nhất để nâng chất lượng codebase. Hãy luyện thói quen với pre‑commit + ruff, dùng checklist trước mỗi PR, và giữ tên tập trung vào ý định. Team bạn (và chính bạn trong tương lai) sẽ biết ơn điều đó.