Cách viết chú thích nhiều dòng trong mã PHP

PHP Tutorial | 17/06/2025 by Học PHP

Trong quá trình lập trình, việc giữ cho mã nguồn rõ ràng, dễ hiểu và dễ bảo trì là điều vô cùng quan trọng. Một trong những công cụ hỗ trợ lập trình viên thực hiện điều đó chính là comment – hay còn gọi là chú thích trong mã. Trong PHP, ngoài việc sử dụng chú thích một dòng để ghi chú ngắn gọn, chú thích nhiều dòng (multi-line comment) cũng đóng vai trò thiết yếu khi cần mô tả logic phức tạp, giải thích từng khối mã, hoặc ghi chú các thông tin quan trọng như tác giả, ngày tạo, mục đích đoạn mã.

Việc sử dụng comment nhiều dòng đúng cách giúp không chỉ bản thân lập trình viên dễ dàng hiểu lại đoạn mã sau một thời gian, mà còn tạo điều kiện thuận lợi cho đồng đội trong quá trình làm việc nhóm, bảo trì và mở rộng chương trình. Vậy comment nhiều dòng trong PHP là gì, cú pháp ra sao, và làm thế nào để sử dụng hiệu quả? Hãy cùng tìm hiểu chi tiết trong nội dung dưới đây.

Khái niệm chú thích nhiều dòng trong PHP

Trong lập trình PHP, chú thích nhiều dòng (multi-line comment) là một phần quan trọng giúp lập trình viên giải thích rõ ràng hơn về các khối mã, cấu trúc chương trình, hoặc đơn giản là ghi chú tạm thời. Khác với comment một dòng chỉ ghi chú ngắn gọn trên một dòng, chú thích nhiều dòng cho phép bạn viết nội dung trải dài qua nhiều dòng liên tiếp, rất hữu ích khi cần:

Mô tả chi tiết một đoạn logic phức tạp.
Giải thích ý nghĩa của các biến, hàm, class.
Ghi chú thông tin người viết, ngày tạo, phiên bản.
Tạm thời vô hiệu hóa một đoạn mã trong quá trình kiểm thử.

Đặc điểm của chú thích nhiều dòng:

Không được thực thi khi mã PHP chạy. Tức là trình biên dịch/bộ thông dịch PHP sẽ bỏ qua hoàn toàn phần comment này.
Giúp mã dễ hiểu hơn, đặc biệt khi làm việc nhóm hoặc xem lại sau thời gian dài.
Có thể dùng để đánh dấu những việc cần làm (TODO), cảnh báo (NOTE, FIXME), hoặc mô tả logic tổng quát của cả chương trình.

Ví dụ thực tế về mô tả dài

/*
    Hàm tính chu vi hình tròn
    Sử dụng công thức: C = 2 * π * r
    Trong đó: r là bán kính hình tròn
    Giá trị π được gán là 3.14 (ước lượng)
*/
function tinhChuVi($r) {
    return 2 * 3.14 * $r;
}

Nhờ đoạn comment nhiều dòng này, người đọc hiểu được ý nghĩa, công thức, và logic mà không cần phân tích lại từng dòng mã.

Lưu ý quan trọng

Chú thích nhiều dòng luôn được đặt trong cặp dấu /* để mở và */ để kết thúc.
Nếu quên đóng dấu */, toàn bộ phần phía sau sẽ bị hiểu nhầm là comment → gây lỗi cú pháp nghiêm trọng.

Cú pháp chú thích nhiều dòng trong PHP

Cú pháp chuẩn

Trong PHP, để viết chú thích nhiều dòng, bạn sử dụng cặp ký hiệu:

/* ... nội dung comment ... */

Tất cả nội dung nằm giữa /* và */ sẽ được xem là phần chú thích và không được thực thi bởi trình thông dịch PHP, dù đó có là dòng lệnh PHP hợp lệ.

Tác dụng của cú pháp này

Bạn có thể sử dụng comment nhiều dòng để:

Ghi chú dài mô tả đoạn mã phức tạp.
Ghi chú nhiều dòng thông tin như tác giả, ngày viết, mô tả chức năng.
Vô hiệu hóa tạm thời một đoạn mã khi đang thử nghiệm.
Đánh dấu các phần cần xử lý sau như TODO, FIXME, NOTE.

Ví dụ minh họa

Ví dụ 1: Mô tả đoạn mã

<?php
/*
    Hàm chào người dùng
    Trả về chuỗi "Xin chào, [Tên]"
    Dùng nối chuỗi bằng dấu .
*/
function chaoNguoiDung($ten) {
    return "Xin chào, " . $ten;
}
?>

Ví dụ 2: Ghi chú thông tin tác giả và chức năng chương trình

<?php
/*
    Tác giả: Nguyễn Ngọc Hoa
    Ngày tạo: 16/06/2025
    Mục đích: Tính tổng 2 số do người dùng nhập
*/
$a = 10;
$b = 15;
echo $a + $b;
?>

Ví dụ 3: Tạm thời ẩn một đoạn mã

<?php
/*
echo "Dòng này đang được kiểm tra, tạm thời ẩn đi";
echo "Có thể dùng lại sau";
*/

echo "Chỉ dòng này được hiển thị.";
?>

Lưu ý khi sử dụng

Luôn đóng đúng cặp */ nếu không sẽ gây lỗi cú pháp nghiêm trọng.
PHP không hỗ trợ lồng chú thích nhiều dòng. Tránh trường hợp sau:

/*
    Đây là dòng đầu
    /*
        Đây là dòng bị lồng – SAI!
    */
*/

Chỉ dùng comment nhiều dòng khi thực sự cần ghi chú dài. Nếu chỉ cần ghi chú ngắn, nên dùng // hoặc # cho gọn gàng.

Ví dụ minh họa chú thích nhiều dòng trong PHP

Chú thích giải thích đoạn mã

Khi viết các hàm hoặc đoạn logic phức tạp, bạn nên sử dụng chú thích nhiều dòng để mô tả công thức, ý nghĩa của tham số hoặc kết quả trả về. Điều này giúp người khác (hoặc chính bạn sau này) hiểu rõ mục đích đoạn mã.

<?php
/*
    Hàm tính diện tích hình chữ nhật
    Công thức: diện tích = chiều dài * chiều rộng
    Tham số:
        $dai – chiều dài hình chữ nhật
        $rong – chiều rộng hình chữ nhật
    Kết quả: trả về diện tích
*/
function tinhDienTich($dai, $rong) {
    return $dai * $rong;
}

echo "Diện tích: " . tinhDienTich(5, 3); // Kết quả: 15
?>

Tạm thời vô hiệu hóa đoạn mã

Trong quá trình kiểm thử, bạn có thể dùng chú thích nhiều dòng để tạm thời ẩn đoạn mã, thay vì xóa đi. Đây là cách rất hữu ích khi muốn giữ lại đoạn mã để kiểm tra hoặc dùng lại sau.

<?php
/*
echo "Dòng 1";
echo "Dòng 2";
*/

echo "Dòng 3"; // Chỉ dòng này được thực thi
?>

Kết quả in ra: Dòng 3

Chú thích mô tả toàn bộ chương trình

Trước mỗi file chương trình, đặc biệt là các tệp quan trọng hoặc dùng chung, bạn nên ghi chú các thông tin meta như: tên tác giả, ngày viết, phiên bản, mục đích của tệp. Điều này thể hiện tính chuyên nghiệp và giúp quản lý mã dễ hơn.

<?php
/*
    Tác giả: Nguyễn Ngọc Hoa
    Mục đích: Tính tổng hai số nguyên
    Ngày tạo: 16/06/2025
    Phiên bản: v1.0
*/

$a = 7;
$b = 5;
echo "Tổng: " . ($a + $b);
?>

Kết quả in ra: Tổng: 12

Chú thích TODO hoặc NOTE trong quá trình phát triển

Lập trình viên thường ghi chú các việc cần làm hoặc lưu ý đặc biệt bằng từ khóa TODO, NOTE, FIXME để dễ tra cứu.

<?php
/*
    TODO: Viết thêm điều kiện kiểm tra đầu vào
    NOTE: Hàm này chưa xử lý trường hợp số âm
*/
function tinhCanBacHai($x) {
    return sqrt($x);
}
?>

Lưu ý khi sử dụng chú thích nhiều dòng trong PHP

Khi sử dụng chú thích nhiều dòng (/* ... */), bạn cần tuân thủ một số nguyên tắc để tránh lỗi và đảm bảo mã nguồn rõ ràng, dễ hiểu. Dưới đây là những lưu ý quan trọng kèm ví dụ minh họa:

Luôn phải đóng */ để tránh lỗi cú pháp

Nếu bạn mở chú thích bằng /* nhưng quên đóng bằng */, toàn bộ phần mã tiếp theo sẽ bị coi là phần chú thích và gây lỗi khi thực thi.

Ví dụ sai (quên đóng `*/`):

<?php
/*
    Đây là chú thích nhiều dòng bị thiếu đóng
echo "Chương trình bị lỗi";

Lỗi: Trình thông dịch PHP sẽ báo lỗi cú pháp vì không tìm thấy điểm kết thúc của comment.

Ví dụ đúng:

<?php
/*
    Đây là chú thích nhiều dòng hợp lệ
*/
echo "Chạy bình thường!";
?>

Không lồng chú thích nhiều dòng vào nhau

PHP không hỗ trợ lồng comment nhiều dòng. Việc dùng /* ... /* ... */ ... */ sẽ làm PHP hiểu sai vị trí kết thúc comment và dẫn đến lỗi.

Ví dụ sai:

<?php
/*
    Đây là chú thích chính
    /*
        Đây là chú thích lồng bên trong – không hợp lệ
    */
*/
?>

Lỗi: Chú thích sẽ kết thúc sớm tại */ bên trong, khiến đoạn còn lại trở thành mã bị lỗi.

Cách xử lý đúng:

Thay vì lồng comment, bạn có thể dùng comment một dòng bên trong:

<?php
/*
    Đây là chú thích chính
    // Đây là dòng giải thích phụ dùng comment 1 dòng
*/
?>

Không nên dùng chú thích nhiều dòng cho ghi chú quá ngắn

Đối với các ghi chú ngắn gọn, nên dùng // hoặc # để mã ngắn gọn và dễ đọc hơn.

Không nên:

<?php
/* Ghi chú ngắn */
echo "Xin chào!";
?>

Nên:

<?php
// Ghi chú ngắn
echo "Xin chào!";
?>

Lỗi thường gặp khi dùng chú thích nhiều dòng trong PHP

Quên đóng */ → gây lỗi cú pháp

Nếu bạn mở chú thích nhiều dòng bằng /* mà không đóng bằng */, trình biên dịch PHP sẽ hiểu toàn bộ phần còn lại là comment, gây lỗi cú pháp hoặc mã không chạy.

Ví dụ sai:

<?php
/*
    Đây là comment mở nhưng bị thiếu dấu đóng
echo "Hello"; // đoạn này không được thực thi

Ví dụ đúng:

<?php
/*
    Đây là comment hợp lệ
*/
echo "Hello"; // Được thực thi bình thường
?>

Viết chú thích không đúng với chức năng thực tế

Chú thích sai nội dung hoặc không cập nhật khi thay đổi mã có thể gây hiểu nhầm nghiêm trọng.

Ví dụ sai:

<?php
/*
    Hàm này tính diện tích hình tròn
*/
function tinhDienTich($a, $b) {
    return $a * $b; // Thực tế là diện tích hình chữ nhật!
}
?>

Cách sửa đúng:

<?php
/*
    Hàm tính diện tích hình chữ nhật
    Công thức: chiều dài * chiều rộng
*/
function tinhDienTich($a, $b) {
    return $a * $b;
}
?>

Chú thích quá dài hoặc không cần thiết

Viết quá nhiều comment không liên quan hoặc mô tả những điều hiển nhiên sẽ làm mã dài dòng, loãng, khó đọc.

Không nên:

<?php
/*
    Đây là biến số nguyên
    Biến này có giá trị là 5
    Chúng ta sẽ dùng biến này để làm gì đó
    Thực ra cũng chưa chắc
*/
$a = 5;
?>

Nên:

<?php
// Khởi tạo biến đếm
$a = 5;
?>

Mẹo viết chú thích nhiều dòng hiệu quả bằng PHP

Chỉ chú thích khi cần thiết

Chỉ dùng comment nhiều dòng để giải thích các đoạn logic phức tạp, mô tả chức năng quan trọng, hoặc ghi chú tổ chức mã.

Ví dụ:

<?php
/*
    Tính thuế VAT cho sản phẩm
    Công thức: giá * thuế suất
    Thuế suất hiện tại: 10%
*/
function tinhVAT($gia) {
    return $gia * 0.1;
}
?>

Sử dụng comment để mô tả hàm, class hoặc file

Ghi chú về hàm, thông tin tác giả, ngày viết, mục đích, giúp dễ quản lý và bảo trì về sau.

<?php
/*
    Tác giả: Nguyễn Ngọc Hoa
    Mô tả: Xử lý đăng nhập người dùng
    Ngày tạo: 16/06/2025
*/
?>

Kết hợp các từ khóa TODO, FIXME, NOTE

Sử dụng các từ khóa đặc biệt để giúp nhóm phát triển dễ tra cứu các việc cần làm, lỗi đang chờ xử lý, hoặc lưu ý quan trọng.

<?php
/*
    TODO: Thêm kiểm tra định dạng email người dùng
    FIXME: Lỗi xử lý khi nhập mật khẩu sai
    NOTE: Tạm thời chưa kết nối với cơ sở dữ liệu
*/
?>

Đặt comment trước đoạn mã cần chú thích

Không nên để comment cách xa đoạn mã sẽ gây khó hiểu.

<?php
/*
    Kiểm tra người dùng có quyền truy cập không
*/
if ($isAdmin) {
    echo "Chào quản trị viên!";
}
?>

Kết bài

Chú thích nhiều dòng trong PHP không chỉ giúp mã nguồn rõ ràng, dễ hiểu mà còn là công cụ quan trọng để tổ chức, bảo trì và làm việc nhóm hiệu quả. Việc sử dụng đúng cú pháp /* ... */ và đặt chú thích đúng chỗ sẽ giúp người lập trình – dù là chính bạn trong tương lai – dễ dàng đọc lại, sửa đổi hoặc mở rộng chương trình.

Tuy nhiên, hãy ghi nhớ rằng viết chú thích cũng cần có chiến lược: chỉ nên chú thích khi cần thiết, tránh dư thừa, đảm bảo nội dung đúng với chức năng thực tế của mã. Đặc biệt, đừng quên tận dụng các từ khóa như TODO, FIXME, hay NOTE để tăng tính chuyên nghiệp và hỗ trợ cộng tác hiệu quả hơn.