Đọc hiểu codebase lạ nhanh trong tuần đầu
Nhận một dự án lạ với hàng trăm file, không biết bắt đầu từ đâu là cảm giác quen thuộc của mọi dev. Đọc từ đầu tới cuối là cách chậm nhất và dễ nản nhất. Bài này chỉ cho bạn một cách tiếp cận có chủ đích: đi từ điểm vào, lần theo đúng một luồng thật, và dùng test cùng lịch sử git làm bản đồ. Sau tuần đầu, bạn đủ tự tin sửa bug đầu tiên mà không phá vỡ thứ khác.
Đừng đọc để nhớ, hãy đọc để trả lời câu hỏi
Sai lầm lớn nhất là cố nạp toàn bộ codebase vào đầu. Não không hoạt động vậy. Thay vào đó, mỗi lần mở code hãy mang theo một câu hỏi cụ thể: “Khi người dùng bấm nút đăng nhập thì chuyện gì xảy ra?” Câu hỏi giúp bạn lọc bỏ 95% code không liên quan và chỉ theo đúng con đường bạn cần.
Bản chất của việc hiểu một hệ thống là hiểu các luồng dữ liệu chính, không phải thuộc từng hàm. Nắm được ba bốn luồng quan trọng nhất là bạn đã hiểu phần lõi.
Lộ trình bốn bước cho tuần đầu
1. Chạy được dự án trước đã
Trước khi đọc dòng nào, hãy dựng môi trường và chạy cho ứng dụng lên. Việc này dạy bạn cấu hình, biến môi trường, cách khởi động và các phụ thuộc thật. Một dự án bạn không chạy được là một dự án bạn chưa thể sửa.
2. Tìm điểm vào
Mọi hệ thống đều có điểm vào: hàm main, file khởi động server, danh sách route, hoặc file cấu hình định tuyến. Từ đó bạn thấy hệ thống nhận yêu cầu ở đâu và đẩy đi đâu. Đây là gốc của bản đồ.
3. Lần theo đúng một luồng từ đầu tới cuối
Chọn một chức năng thật, ví dụ đăng nhập. Đi từ route tới controller, tới lớp nghiệp vụ, tới truy vấn database rồi ngược ra response. Dùng tính năng nhảy tới định nghĩa của trình soạn thảo để đi theo. Chỉ một luồng trọn vẹn dạy bạn kiến trúc nhiều hơn cả ngày lướt ngẫu nhiên.
4. Đọc test để hiểu ý định
Test là tài liệu sống. Chúng cho biết đầu vào mong đợi, đầu ra đúng, và các trường hợp biên mà tác giả lo lắng. Đọc tên các test là bạn nắm được hệ thống được kỳ vọng làm gì.
Dùng công cụ làm bản đồ
| Bạn muốn biết | Cách nhanh nhất |
| Một hàm được gọi từ đâu | Tìm tất cả tham chiếu trong IDE |
| Vì sao một dòng code tồn tại | git blame để xem commit và lý do gốc |
| Một tính năng nằm ở file nào | Tìm theo chuỗi text hiển thị trên giao diện |
| Cách một module được dùng đúng | Đọc test tương ứng của module đó |
Ví dụ thực tế
Bạn nhận một API bán hàng và được giao sửa lỗi tính sai phí ship. Thay vì đọc cả repo, bạn tìm chuỗi “shipping” trong code, ra một hàm tính phí. Dùng tìm tham chiếu, thấy nó được gọi từ bước tạo đơn. Lần ngược lên route tạo đơn, bạn hiểu toàn bộ luồng: nhận giỏ hàng, tính tiền hàng, gọi hàm phí ship, cộng tổng. Mở test của hàm phí ship, bạn thấy một trường hợp biên chưa được xử lý là đơn nhiều kho. Chưa cần hiểu toàn hệ thống, bạn đã đủ ngữ cảnh để sửa đúng chỗ. Đó là sức mạnh của việc lần theo một luồng thay vì đọc dàn trải.
Lỗi thường gặp và cách khắc phục
Cố hiểu tất cả trước khi làm gì
Bạn sẽ chìm trong chi tiết và mất động lực. Hãy nhắm tới một thay đổi nhỏ có thật càng sớm càng tốt, dù chỉ là sửa một dòng log.
Bỏ qua việc chạy dự án
Đọc code chay khiến bạn hiểu sai hành vi runtime. Chạy thật và thử tương tác giúp xác nhận giả định.
Ngại hỏi nhưng hỏi sai cách
Đừng hỏi “code này chạy sao” chung chung. Hãy tự tìm tới 80%, rồi hỏi câu cụ thể: “Tôi thấy luồng đi tới đây rồi rẽ nhánh, vì sao lại có nhánh này?” Câu hỏi cụ thể tôn trọng thời gian đồng nghiệp và cho bạn câu trả lời tốt.
Không ghi chú lại
Vẽ một sơ đồ luồng đơn giản hay ghi vài dòng cho chính mình. Tuần sau bạn sẽ cảm ơn bản thân.
Checklist tuần đầu
- Tôi đã dựng và chạy được dự án trên máy chưa?
- Tôi đã xác định điểm vào của hệ thống?
- Tôi đã lần trọn một luồng nghiệp vụ từ đầu tới cuối?
- Tôi đã đọc test để hiểu ý định thiết kế?
- Tôi có dùng tìm tham chiếu và git blame khi bí?
- Tôi đã thực hiện một thay đổi nhỏ và thấy nó có tác dụng?
- Tôi có ghi chú lại bản đồ của riêng mình?
Kết luận
Hiểu codebase lạ không phải đọc nhiều nhất, mà là đọc đúng đường. Bắt đầu bằng việc chạy dự án và lần theo đúng một luồng thật ngay hôm nay. Khi bạn đi trọn một con đường, những con đường còn lại sẽ trông quen thuộc hơn nhiều.
Câu hỏi thường gặp
Nên đọc code hay đọc tài liệu trước?
Đọc tài liệu để có bức tranh tổng thể và thuật ngữ, nhưng đừng tin tuyệt đối vì tài liệu hay lỗi thời. Code và test mới là sự thật cuối cùng về hành vi hệ thống.
Codebase không có test thì dựa vào đâu?
Dựa vào việc chạy thật và log. Thêm log tạm vào luồng bạn quan tâm, tương tác với ứng dụng, quan sát dữ liệu chảy qua. Dùng git blame để hiểu ý định của các commit cũ.
Bao lâu thì nên tự tin sửa bug đầu tiên?
Không cần hiểu cả hệ thống. Khi bạn đã lần trọn được luồng chứa bug và hiểu dữ liệu ra vào của vùng đó, bạn đủ ngữ cảnh để sửa an toàn, thường là trong vài ngày đầu.
Làm sao tránh phá vỡ thứ khác khi mới vào?
Thay đổi nhỏ, có phạm vi rõ ràng. Chạy test hiện có trước và sau khi sửa. Nếu vùng đó chưa có test, viết một test nhỏ khoanh vùng hành vi trước khi động vào.
Nguồn tham khảo
- Sách “Working Effectively with Legacy Code” của Michael Feathers
- Tài liệu chính thức của Git về git blame và git log
