Kỹ năng làm việc với codebase lớn

Bạn vừa join vào một dự án mới. Clone repo về, mở ra và thấy... 5.000 file, 300.000 dòng code. Không biết bắt đầu từ đâu. Không hiểu luồng chạy. Sợ đụng vào là vỡ cả hệ thống.

Đây là cảm giác mà hầu hết developer đều trải qua ít nhất một lần. Và cách bạn xử lý nó sẽ quyết định bạn là senior hay mãi loay hoay ở junior.

Bài này chia sẻ kỹ năng thực chiến để làm việc hiệu quả với codebase lớn — không phải lý thuyết, mà là thứ dev thực tế đang dùng hàng ngày.

1. Kỹ năng đọc code

Sai lầm lớn nhất là mở file ra đọc từng dòng một. Với codebase lớn, bạn cần hiểu toàn cảnh trước khi đi vào chi tiết.

Việc đầu tiên khi tiếp cận codebase mới:

Đọc README.md — nghe có vẻ hiển nhiên nhưng 70% dev bỏ qua bước này
Xem cấu trúc thư mục: tree -L 3 hoặc dùng IDE để có cái nhìn tổng quan
Tìm file entry point: index.js, index.php, app.py... đây là cửa vào của hệ thống
Đọc file config: .env.example, config/, docker-compose.yml — hiểu hệ thống phụ thuộc vào gì

Mục tiêu: sau 30 phút, bạn phải vẽ được sơ đồ tổng quan của hệ thống — dù thô sơ. Cái gì giao tiếp với cái gì, data chạy theo hướng nào.

Vẽ sơ đồ call graph khi gặp file phức tạp

mergeMemo()
    └── mergeAnnotation()
            ├── getWindData()
            ├── mergeWindData()
            │       ├── findSameObjectKey()
            │       └── mergeWindDetails()
            │               └── mergeWindValues()
            │                       └── findObject()
            └── saveWindData()

Đặt câu hỏi trước khi đọc

"Hàm này làm gì?" → chỉ đọc input/output
"Bug ở đâu?"      → chỉ đọc điều kiện if/else
"Data từ đâu?"    → chỉ đọc FROM, JOIN, parameter

💡 Tip: Dùng Mermaid hoặc Draw.io vẽ ngay, đừng để trong đầu. Diagram thô còn hơn không có diagram.

2. Trace ngược từ feature — không đọc code từ đầu

Bạn cần fix bug ở tính năng checkout? Bắt đầu từ tính năng đó, trace ngược lên — đừng đọc từ đầu file.

Quy trình trace ngược hiệu quả:

Tìm route hoặc endpoint liên quan: grep -r "checkout" routes/
Từ route → tìm controller xử lý
Từ controller → tìm service/model được gọi
Từ service → hiểu business logic thực sự

Với Laravel ví dụ:

# Tìm route liên quan đến checkout
grep -rn "checkout" routes/web.php routes/api.php

# Tìm tất cả nơi một method được gọi
grep -rn "processPayment" app/

Cách này giúp bạn chỉ đọc đúng phần cần thiết, không bị lạc trong biển code không liên quan.

3. Thành thạo công cụ tìm kiếm trong IDE

Với codebase lớn, tìm kiếm là siêu năng lực. Dev giỏi không nhớ tất cả mọi thứ — họ biết cách tìm nhanh.

Các phím tắt không thể thiếu trong VSCode:

Ctrl+Shift+F — Tìm kiếm toàn bộ project
Ctrl+Shift+O — Tìm symbol (function, class) trong file hiện tại
F12 — Go to definition
Shift+F12 — Find all references — cực kỳ quan trọng khi refactor
Ctrl+P — Tìm file nhanh theo tên
Alt+F12 — Peek definition — xem code mà không rời khỏi file hiện tại

Ngoài IDE, ripgrep (rg) là công cụ tìm kiếm terminal nhanh hơn grep nhiều lần:

# Tìm tất cả nơi dùng một constant
rg "MAX_RETRY_COUNT" --type php

# Tìm với context 3 dòng trên dưới
rg "sendEmail" -C 3

4. Đọc test trước khi đọc code

Test case là documentation sống của codebase. Nó cho bạn biết:

Function này nhận input gì, trả về gì
Edge case nào đã được xử lý
Business logic thực sự là gì (không phải những gì dev nghĩ)

Khi vào một module mới, hãy tìm file test tương ứng đọc trước. Ví dụ:

# Tìm test file cho UserService
find . -name "*UserService*Test*" -o -name "*test*user*service*"

Nếu codebase không có test — đó là dấu hiệu đỏ, và bạn cần cẩn thận gấp đôi khi thay đổi bất cứ thứ gì.

5. Dùng Git như một công cụ khám phá

Git history là cuốn nhật ký của codebase. Nó cho bạn biết tại sao code được viết như vậy, không chỉ là gì.

Các lệnh git cực kỳ hữu ích:

# Xem ai đã thay đổi từng dòng trong file (và commit message)
git blame src/Payment/PaymentService.php

# Tìm commit nào đã thêm một đoạn code cụ thể
git log -S "processRefund" --oneline

# Xem lịch sử thay đổi của một file cụ thể
git log --follow -p src/models/Order.php

# Tìm commit theo nội dung message
git log --grep="fix payment" --oneline

Thường xuyên bạn sẽ tìm thấy comment trong commit message giải thích "tại sao code này kỳ lạ như vậy" — điều mà code không bao giờ nói với bạn.

6. Hiểu kiến trúc — không chỉ đọc code

Codebase lớn thường follow một kiến trúc nhất định. Hiểu kiến trúc giúp bạn đoán được file ở đâu, code được tổ chức thế nào mà không cần tìm kiếm.

Các pattern phổ biến cần biết:

MVC: Model-View-Controller — phổ biến trong Laravel, Rails, Django
Repository Pattern: Tách database query ra khỏi business logic
Service Layer: Business logic nằm trong Service class, không phải Controller
Event-Driven: Code giao tiếp qua event/listener thay vì gọi trực tiếp
Microservices: Mỗi service độc lập, giao tiếp qua API hoặc message queue

Khi hiểu kiến trúc, bạn biết: "Feature này liên quan đến payment, chắc chắn có PaymentService, PaymentRepository, và event PaymentProcessed" — thay vì mò mẫm từng file.

7. Ghi chép liên tục — đừng tin vào trí nhớ

Khi làm việc với codebase lớn, bạn sẽ khám phá ra nhiều thứ. Ghi lại tất cả, ngay lập tức.

Tạo file NOTES.md trong project (thêm vào .gitignore) và ghi:

# Notes - Project XYZ

## Luồng xử lý Order
1. User tạo order → OrderController@store
2. Validate → OrderRequest
3. Business logic → OrderService@createOrder
4. Lưu DB → OrderRepository
5. Fire event → OrderCreated
6. Listener gửi email → SendOrderConfirmationEmail

## Gotchas / Điểm cần chú ý
- Đừng sửa trực tiếp bảng orders — phải qua OrderService
- Config payment timeout ở .env: PAYMENT_TIMEOUT=30
- Module shipping chưa được refactor, code cũ, cần cẩn thận

## Câu hỏi cần hỏi team
- Tại sao dùng raw query ở UserRepository line 145?
- Background job PaymentRetryJob chạy schedule như thế nào?

Ghi chép này vừa giúp bạn không quên, vừa là tài liệu quý giá cho người join sau.

8. Chạy code trước khi đọc code

Đừng chỉ đọc static code. Chạy nó lên, observe behavior thực tế.

Kỹ thuật:

Thêm log tạm thời: console.log, dd() trong Laravel, print_r() — để xem data thực tế chạy qua
Dùng debugger: Breakpoint trong Xdebug, Node debugger — xem call stack, variable state
Dùng profiler: Xem query nào chạy, function nào tốn thời gian nhất

Ví dụ với Laravel Debugbar — bật lên và bạn thấy ngay:

Bao nhiêu SQL query được thực thi
Query nào chậm
Memory usage
Route nào đang được xử lý

💡 Tip: "Chạy thử" nhanh hơn "đọc hiểu" rất nhiều lần. Một dd($variable) tiết lộ ngay structure của data mà bạn phải đọc 20 phút mới hiểu.

9. Hỏi đúng cách — đừng hỏi lăng nhăng

Trong dự án lớn, có team. Team là nguồn kiến thức quý nhất. Nhưng hỏi đúng cách mới được giúp đỡ thực sự.

Hỏi sai:

"Em không hiểu module payment, anh giải thích cho em với?"

Hỏi đúng:

"Em đang trace flow xử lý refund. Em thấy RefundService@process gọi PaymentGateway@refund, nhưng không hiểu tại sao ở line 87 lại có thêm bước holdBalance trước khi refund. Anh có thể giải thích logic đó không?"

Câu hỏi tốt cho thấy bạn đã tự nghiên cứu, và giúp người trả lời biết chính xác cần giải thích gì.

10. Dùng AI để accelerate — không phải để thay thế hiểu biết

Claude Code, Cursor AI, GitHub Copilot — những tool này cực kỳ hữu ích với codebase lớn. Nhưng dùng đúng cách:

Dùng AI để explain code: Paste một đoạn code phức tạp, hỏi "Explain this code và tại sao nó cần làm vậy"
Dùng AI để tìm pattern: "Trong codebase này, convention để xử lý error là gì?"
Dùng AI để generate boilerplate: Những thứ lặp đi lặp lại, theo đúng pattern có sẵn

Nhưng đừng để AI đọc hiểu thay bạn. Nếu AI giải thích một đoạn code mà bạn không verify lại được bằng cách tự đọc — bạn đang xây nhà trên nền cát.

11. Kỹ năng debug

Reproduce trước, fix sau

Không bao giờ sửa code khi chưa reproduce được bug
→ Hiểu rõ input nào gây ra output sai
→ Mới biết cần sửa chỗ nào

Tách biệt "hiểu code" và "sửa code"

Bước 1: Hiểu code đang làm gì (không sửa gì)
Bước 2: Xác định vấn đề ở đâu
Bước 3: Mới bắt đầu sửa

Giả định → kiểm chứng

Thay vì đọc hết → mới kết luận:

Giả định: "Bug nằm ở thứ tự seqSelectList"
→ Đọc đúng chỗ đó để kiểm chứng
→ Đúng → tiếp tục
→ Sai → giả định mới

Tổng kết

Làm việc với codebase lớn không phải là cuộc thi nhớ code. Đó là khả năng navigate hệ thống phức tạp một cách có hệ thống.

3 điều cốt lõi cần nhớ:

Top-down trước, bottom-up sau — Hiểu toàn cảnh trước khi đào sâu chi tiết
Trace, đừng đọc — Follow luồng thực tế thay vì đọc từ đầu đến cuối
Ghi chép mọi thứ — Trí nhớ ngắn hạn, ghi chú thì không

Kỹ năng này không đến ngay trong một ngày. Nhưng mỗi lần tiếp cận codebase mới với mindset đúng, bạn sẽ thấy mình master nó nhanh hơn lần trước.