Hàm

01 Nhỏ! (Small!)

Hàm lý tưởng dài 2–4 dòng, hiếm khi quá 20 dòng. Mỗi hàm "trong suốt rõ ràng", kể một câu chuyện và dẫn bạn sang hàm kế theo một trật tự cuốn hút.

RAG  Khâu nạp tài liệu (ingest) hay phình to vì vòng lặp lồng điều kiện. Kéo khối bên trong ra thành lời gọi hàm có tên:

def ingest(path):
    for doc in load(path):
        if doc.lang == "vi":           # thụt lề 3–4 cấp
            text = clean(doc.text)
            for chunk in split(text, 800):
                if len(chunk) > 50:
                    vec = embed(chunk)
                    store.add(vec, chunk)

def ingest(path):
    for doc in load(path):
        index_document(doc)            # khối trong for = 1 lời gọi hàm

def index_document(doc):
    if doc.lang != "vi":
        return
    for chunk in meaningful_chunks(doc):
        store.add(embed(chunk), chunk)

02 Chỉ làm một việc

Khó ở chỗ "một việc" là gì? Định nghĩa của Martin rất thực dụng:

RAG  Hàm answer dễ ôm đồm: vừa truy hồi, vừa ghép prompt cấp thấp, vừa gọi API, vừa log. Hạ nó về một orchestrator gồm các bước cùng mức:

def answer(q):
    hits = store.search(embed(q), k=5)          # cấp cao
    prompt = "Context:\n"
    for h in hits:
        prompt += "- " + h.text + "\n"           # cấp thấp: ghép chuỗi
    prompt += "Q: " + q
    resp = llm.chat(prompt)                       # cấp cao
    log.info("answered %s", q); return resp.text  # lẫn cả việc khác

def answer(q):                        # mọi bước cùng một mức
    context = retrieve(q)
    return generate(q, context)

def retrieve(q):
    return store.search(embed(q), k=5)

def build_prompt(q, context):         # chi tiết cấp thấp gói riêng
    lines = [f"- {h.text}" for h in context]
    return "Context:\n" + "\n".join(lines) + f"\nQ: {q}"

03 Một mức trừu tượng & Quy tắc Stepdown

Trộn các mức trừu tượng trong một hàm luôn gây nhầm lẫn — vừa gọi get_html() (cấp cao) vừa .append("\n") (cấp thấp). Mỗi hàm hãy giữ đúng một mức.

Đọc như các đoạn "ĐỂ … ta …"

Mỗi cấp chỉ tham chiếu cấp ngay dưới — đó chính là cách giữ hàm nhỏ và "làm một việc". Học theo được Stepdown là khó, nhưng là chìa khóa.

04 Câu lệnh Switch & đa hình

Bản chất switch (và chuỗi if/elif) là luôn làm N việc. Một switch chọn-theo-loại còn vi phạm:

RAG  Quy tắc của Martin: switch chấp nhận được nếu chỉ xuất hiện một lần, dùng để tạo đối tượng đa hình, và bị giấu sau một factory. Ví dụ chọn nhà cung cấp embedding:

def embed(text, provider):              # switch lặp khắp nơi
    if provider == "openai":  return openai_embed(text)
    elif provider == "cohere": return cohere_embed(text)
    elif provider == "local":  return local_embed(text)
    raise UnknownProvider(provider)
# … cùng switch này còn lặp ở rerank(), summarize(), …

class Embedder(Protocol):
    def embed(self, text: str) -> list[float]: ...

def make_embedder(provider) -> Embedder:   # switch CHỈ ở đây
    return {"openai": OpenAIEmbedder,
            "cohere": CohereEmbedder,
            "local": LocalEmbedder}[provider]()
# nơi dùng: embedder.embed(text) — đa hình, không thấy switch

05 Đối số của hàm (Function Arguments)

Đối số "ngốn năng lực tư duy" và làm việc kiểm thử bùng nổ tổ hợp. Càng ít càng tốt:

Tránh đối số cờ (flag argument)

Truyền một boolean vào hàm là tuyên bố oang oang rằng hàm làm hai việc — một việc nếu cờ True, việc khác nếu False. Hãy tách đôi:

def search(query, rerank):       # cờ → search(q, True) khó hiểu
    hits = vector_search(query)
    if rerank:
        hits = rerank_hits(query, hits)
    return hits

def search(query):
    return vector_search(query)

def search_reranked(query):      # hai ý định gọi → hai hàm tên rõ
    return rerank_hits(query, search(query))

06 Không tác dụng phụ & Tách Lệnh–Truy vấn

Ví dụ kinh điển: checkPassword nghe như chỉ kiểm tra, nhưng lại lén gọi Session.initialize() — tạo ràng buộc thời gian (temporal coupling): chỉ gọi được "đúng lúc", gọi sai thứ tự là mất dữ liệu phiên.

RAG  Một hàm "truy vấn" mà lén thay đổi trạng thái là cùng một cái bẫy:

def is_relevant(chunk, query):     # tên: chỉ trả lời câu hỏi
    score = cosine(embed(query), chunk.vector)
    cache.clear()                  # tác dụng phụ ẩn → temporal coupling
    return score >= 0.7

def is_relevant(chunk, query):     # TRUY VẤN: chỉ trả lời, không đổi gì
    return cosine(embed(query), chunk.vector) >= 0.7

def reset_cache():                 # LỆNH: tách riêng, gọi tường minh khi cần
    cache.clear()

07 Ưu tiên Exception thay mã lỗi

Trả về mã lỗi vi phạm CQS (lệnh bị dùng như biểu thức trong if) và đẩy người gọi vào các cấu trúc if lồng sâu để xử lý lỗi ngay. Dùng exception, rồi tách khối try/catch ra hàm riêng.

def delete_doc(doc):                       # mã lỗi → if lồng sâu
    if store.delete(doc) == OK:
        if registry.delete_ref(doc.name) == OK:
            if keys.delete(doc.key) == OK:
                return OK
    return ERROR

def delete_doc(doc):                  # try là từ đầu tiên, hết sau except
    try:
        _delete_doc_and_refs(doc)
    except StoreError as e:
        log_error(e)

def _delete_doc_and_refs(doc):        # xử lý thường, tách khỏi xử lý lỗi
    store.delete(doc)
    registry.delete_ref(doc.name)
    keys.delete(doc.key)

08 DRY & cách thật sự để viết hàm

Không ai viết hàm sạch ngay lần đầu

Viết phần mềm cũng như viết văn: đổ ý ra trước, rồi gọt cho đến khi đọc xuôi. Martin thừa nhận bản nháp của ông cũng dài, lồng nhiều vòng lặp, tên tùy tiện, lắm đối số.

09 Ghi nhớ nhanh