Mùi code & Kinh nghiệm

01 Catalog là gì & cách dùng

Đây không phải một danh sách quy tắc "học thuộc rồi áp máy móc", mà là một hệ thống giá trị (value system) về code sạch — đúc kết từ kinh nghiệm thực chiến. Mỗi mục được gắn mã hiệu theo nhóm để tham chiếu nhanh.

02 Comments (C1–C5)

Triết lý chung về comment: comment tốt nhất là comment không cần viết vì code đã tự nói. Năm mùi sau là các kiểu comment cần dọn:

03 Environment (E) & Functions (F)

Environment — build & test phải "một thao tác"

Functions — mùi của hàm

04 General — phần 1 (G1–G18)

Nhóm General là lớn & đa dạng nhất. Phần đầu xoay quanh trùng lặp, mức trừu tượng, code chết & tính nhất quán:

RAG  G5 (Duplication) là mùi đáng săn nhất. Trong pipeline RAG, đoạn "nhúng rồi chuẩn hóa vector" hay bị copy ở nhiều nơi — gom lại một chỗ:

def index(chunk):
    v = model.encode(chunk)
    v = v / norm(v)                 # chuẩn hóa — lặp ở đây
    store.add(v, chunk)

def search(query):
    v = model.encode(query)
    v = v / norm(v)                 # …và lặp y hệt ở đây
    return store.knn(v, k=5)

def embed(text):                    # một nguồn chân lý duy nhất
    v = model.encode(text)
    return v / norm(v)

def index(chunk):  store.add(embed(chunk), chunk)
def search(query): return store.knn(embed(query), k=5)

05 General — phần 2 (G19–G36)

Phần sau của General thiên về diễn đạt ý định: biến giải thích, đa hình, đóng gói điều kiện, hằng có tên, luật Demeter…

RAG  G25 (magic number) & G19 (explanatory variable) thường đi cùng nhau — số "thần kỳ" lẫn biểu thức rối trong một dòng lọc kết quả:

def keep(hits):
    return [h for h in hits
            if cosine(q_vec, h.vector) >= 0.78    # 0.78 là gì?
            and len(h.text) > 40]                  # 40 là gì?

RELEVANCE_THRESHOLD = 0.78          # G25: hằng có tên
MIN_CHUNK_CHARS = 40

def keep(hits):
    def is_relevant(h):              # G19: biến/hàm giải thích
        similarity = cosine(q_vec, h.vector)
        long_enough = len(h.text) > MIN_CHUNK_CHARS
        return similarity >= RELEVANCE_THRESHOLD and long_enough
    return [h for h in hits if is_relevant(h)]

RAG  G23 (đa hình thay if/else) & G28 (đóng gói điều kiện): thay vì if theo loại reranker và một biểu thức boolean dài, dùng đa hình + một hàm tên rõ:

def rerank(kind, q, hits):
    if kind == "bm25":   return bm25_rerank(q, hits)
    elif kind == "cross": return cross_encoder(q, hits)   # G23: switch theo loại
    # đóng gói điều kiện?
    if len(hits) > 0 and hits[0].score < 0.3 and not cached(q):
        hits = expand(q, hits)
    return hits

class Reranker(Protocol):           # G23: đa hình, mỗi loại một lớp
    def rerank(self, q, hits): ...

def needs_expansion(q, hits):       # G28: đóng gói điều kiện thành tên rõ
    return hits and hits[0].score < LOW_SCORE and not cached(q)

def rerank(reranker, q, hits):
    out = reranker.rerank(q, hits)
    return expand(q, out) if needs_expansion(q, out) else out

RAG  G36 (Avoid Transitive Navigation — luật Demeter): đừng đi xuyên một chuỗi object để với tới thứ bạn cần.

def top_source(answer):
    # đi xuyên 4 cấp: biết quá nhiều về cấu trúc bên trong
    return answer.context.hits[0].document.metadata.source

def top_source(answer):
    return answer.top_source()      # hỏi object, đừng moi ruột nó

# trong lớp Answer:
def top_source(self):
    return self.context.best_source()   # mỗi cấp chỉ nói với hàng xóm

06 Names (N1–N7)

Tên là công cụ giao tiếp mạnh nhất trong code. Bảy heuristic về đặt tên:

07 Tests (T1–T9)

Một bộ test sạch & đầy đủ là tấm lưới an toàn cho mọi refactor. Chín heuristic về test:

08 Ghi nhớ nhanh