Tính mô-đun & Connascence

01 Modularity là gì & vì sao quan trọng?

Modularity = cách nhóm logic mã nguồn có liên quan với nhau (lớp trong OOP, hàm trong lập trình hàm — package ở Java, namespace ở .NET). Đây vừa là cơ chế tổ chức, vừa là không gian tên (namespace) để tách bạch các tài sản phần mềm.

Ví dụ xuyên suốt: hệ Hỏi–đáp tài liệu (RAG)

Suốt trang này, ta soi các khái niệm qua một hệ RAG thật: Python lo pipeline (chunk → embed → truy hồi → sinh câu trả lời), PHP lo web/API và gọi sang qua HTTP. Chính ranh giới HTTP đó là "khoảng cách module" lớn nhất — nơi connascence mạnh trở nên nguy hiểm.

flowchart LR
  subgraph PHP["PHP · Web / API (Laravel)"]
    W["Upload + câu hỏi"]
  end
  subgraph PY["Python · RAG pipeline (FastAPI)"]
    direction TB
    I["Ingest: load → chunk → embed"]:::m
    Q["Retrieve → Generate"]:::m
    E["Embedder"]:::m
    S[("Vector Store")]:::db
    I --> E --> S
    Q --> E
    Q --> S
  end
  W -->|"POST /ingest"| I
  W -->|"POST /query · CoN·CoT·CoA·CoV"| Q
  classDef m fill:#dbeee8,stroke:#0f7d72,color:#1c1a14;
  classDef db fill:#e2edf3,stroke:#2f6d93,color:#1c1a14;
            

02 Đo lường modularity

Ba nhóm thước đo: Cohesion (bên trong module), Coupling (giữa các module), và các metric dẫn xuất tổng hợp.

Cohesion — module "thuộc về nhau" tới mức nào

Đo mức độ các phần trong một module thực sự liên quan. Thang 7 mức, từ tốt nhất → tệ nhất:

RAG  Gom code theo chức năng, đừng gom theo "tiện tay":

# ✓ Functional — mọi thứ phục vụ ĐÚNG một việc: text → vector
class Embedder:
    def embed(self, text): ...
    def embed_batch(self, texts): ...

# ✗ Coincidental — gom hàm chẳng liên quan chỉ vì "cho tiện"
# helpers.py
def clean_html(s): ...
def parse_pdf(path): ...
def post_to_slack(msg): ...

Coupling — kết nối giữa các thành phần

flowchart LR
  A1[Lớp A]:::in --> C
  A2[Lớp B]:::in --> C
  A3[Lớp D]:::in --> C
  C{{Thành phần C}}:::core --> E1[Lớp X]:::out
  C --> E2[Lớp Y]:::out
  classDef in fill:#dbeee8,stroke:#0f7d72,color:#1c1a14;
  classDef out fill:#e2edf3,stroke:#2f6d93,color:#1c1a14;
  classDef core fill:#14233b,stroke:#14233b,color:#f3ede0;
            

Ba metric dẫn xuất

Distance from the Main Sequence

03 Connascence — sự đồng biến

Connascence tinh chỉnh khái niệm coupling: không chỉ hỏi "có ghép nối không?" mà hỏi "ghép nối theo kiểu gì?". Chia làm hai nhóm: tĩnh (thấy qua đọc mã) và động (chỉ lộ ra lúc chạy).

Static Đồng biến tĩnh — phát hiện qua phân tích mã

void updateSeat(String name, String seatLocation) { ... }

// Cả hai tham số đều là String → trình biên dịch KHÔNG báo lỗi,
// nhưng truyền sai THỨ TỰ thì ngữ nghĩa sai hoàn toàn:
updateSeat("14D", "Ford, N");   // name = "14D"? chỗ ngồi = "Ford, N"?

RAG  CoA xuyên service — cách chuẩn hoá text lúc index phải khớp lúc query, dù ở hai ngôn ngữ:

def normalize(t):
    return t.lower().strip()          # bỏ hoa, gập khoảng trắng
store.add(embed(normalize(doc)))      # vector nằm trong "không gian" đã chuẩn hoá

$q = trim($question);                 // ✗ KHÁC: quên ->lower()
$res = $rag->query($q);               // câu hỏi & tài liệu lệch chuẩn → truy hồi sai

Dynamic Đồng biến động — chỉ lộ lúc chạy

email = new Email();
email.setRecipient("foo@example.com");
email.setSender("me@me.com");
email.send();
email.setSubject("whoops");   // ✗ quá muộn — phải set TRƯỚC khi send()

04 Ba thuộc tính của connascence

Ba "núm xoay" giúp KTS dùng connascence một cách khôn ngoan — luôn cân nhắc Strength & Locality cùng nhau.

Thang độ mạnh — kim chỉ nam refactor

Đổi từ dạng mạnh → yếu để cải thiện coupling. Càng ít chấm càng yếu & càng nên ưu tiên:

RAG  Hạ độ mạnh CoM → CoN: thay "magic number" trạng thái tài liệu bằng hằng số có tên:

# ✗ CoM — "1" nghĩa là gì? phải nhớ quy ước ngầm
if doc.status == 1:                 # 1 = đã index? 2 = đang chạy?
    retrieve(doc)

# ✓ CoN — đặt tên; đổi ở một chỗ, mọi nơi theo tên
class DocStatus(IntEnum):
    PENDING, INDEXED, FAILED = 0, 1, 2
if doc.status == DocStatus.INDEXED:
    retrieve(doc)

05 Cải thiện modularity bằng connascence

Ba quy tắc của Page-Jones

Hai quy tắc của Jim Weirich

Locality qua ví dụ: đừng để PHP "biết quá nhiều" về Python

RAG  Cùng một kiểu ghép nối, nhưng băng qua HTTP (xa) thì phải hạ về dạng yếu:

// ✗ Mạnh & xuyên ranh giới: vị trí tham số (CoP), PHP tự embed (CoA/CoV)
$res = $http->post('/query', [$vector, 5, 'cosine', true]);

// ✓ Hợp đồng mỏng, field có tên (CoN/CoT) — để Python lo embed
$res = $http->post('/query', [
    'question' => $q,     // gửi câu hỏi THÔ
    'top_k'    => 5,
]);

06 Ghi nhớ nhanh