[Clean Code] Docblock: Đừng chỉ viết Code, hãy viết "Hướng dẫn sử dụng" ngay trong Source Code
Bạn đã bao giờ mở một file code cũ của chính mình từ 6 tháng trước và tự hỏi: "Hàm này nhận vào cái gì và trả về cái gì ấy nhỉ?" chưa?
Nếu câu trả lời là "Có", thì bạn đang thiếu Docblock. Trong lập trình, Docblock không chỉ là những dòng comment vô nghĩa, nó là một tiêu chuẩn viết tài liệu (Documentation) giúp IDE hiểu code của bạn hơn và giúp đồng nghiệp (hoặc chính bạn trong tương lai) không phải đi "giải mã" logic.
1. Docblock là gì?
Docblock là một dạng comment đặc biệt, bắt đầu bằng /** và kết thúc bằng */. Khác với comment thông thường (// hoặc /*), Docblock được thiết kế để các công cụ tự động (như IDE, API Generator) có thể đọc và phân tích.
Nó thường đứng trước:
- Class
- Thuộc tính (Property)
- Phương thức (Method/Function)
2. Cấu trúc của một Docblock chuẩn
Một Docblock thường chia làm 3 phần chính:
- Summary: Mô tả ngắn gọn hàm này làm gì.
- Description: Mô tả chi tiết (nếu cần).
- Tags: Các từ khóa bắt đầu bằng dấu @ (như @param, @return, @throws).
3. Các thẻ (Tags) phổ biến nhất
| Thẻ | Ý nghĩa |
|---|---|
| @param | Định nghĩa kiểu dữ liệu và tên của tham số đầu vào. |
| @return | Định nghĩa kiểu dữ liệu mà hàm sẽ trả về. |
| @throws | Liệt kê các ngoại lệ (Exception) mà hàm có thể bắn ra. |
| @var | Dùng để mô tả kiểu dữ liệu của một biến hoặc thuộc tính. |
| @see | Tham chiếu đến một hàm hoặc tài liệu liên quan khác. |
4. Ví dụ thực tế (PHP & Laravel)
Cách viết "ngây ngô":
public function calculate($a, $b) {
return $a + $b;
}
Nhược điểm: Nhìn vào không biết $a, $b là số nguyên, số thực hay là... một mảng?
Cách viết với Docblock chuyên nghiệp:
/**
* Tính tổng doanh thu dựa trên đơn hàng và thuế suất.
* * Hàm này sẽ cộng dồn giá trị đơn hàng và áp dụng công thức thuế VAT hiện hành.
*
* @param float $amount Số tiền gốc của đơn hàng.
* @param float $taxPercent Phần trăm thuế (ví dụ: 0.1 cho 10%).
* @throws InvalidArgumentException Nếu số tiền nhỏ hơn 0.
* @return float Tổng số tiền sau thuế.
*/
public function calculateTotal(float $amount, float $taxPercent): float
{
if ($amount < 0) {
throw new InvalidArgumentException("Số tiền không được âm");
}
return $amount * (1 + $taxPercent);
}
5. Tại sao bạn "phải" viết Docblock?
Hỗ trợ IDE (IntelliSense): Khi bạn gọi hàm ở chỗ khác, VS Code hoặc PHPStorm sẽ hiển thị ngay gợi ý về kiểu dữ liệu và mô tả hàm. Bạn không cần phải nhảy vào tận file gốc để xem nữa.
Tự động tạo tài liệu: Bạn có thể dùng các công cụ như Doxygen, phpDocumentor hoặc Swagger để quét toàn bộ Docblock và xuất ra một trang web hướng dẫn (API Doc) cực kỳ xịn xò.
Hạn chế Bug: Khi quy định rõ @param string $name, nếu bạn vô tình truyền vào một Array, IDE sẽ gạch chân cảnh báo ngay lập tức.
Lời kết
All Rights Reserved
