Cách sử dụng comment trong PHP

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

Trong quá trình viết mã, việc đảm bảo rằng người khác – hoặc chính bạn trong tương lai – có thể dễ dàng hiểu được mục đích và cách hoạt động của từng đoạn mã là điều rất quan trọng. Đó là lý do vì sao comment (chú thích) trở thành một phần không thể thiếu trong lập trình, đặc biệt là với những ngôn ngữ như PHP. Comment không tham gia vào quá trình thực thi chương trình, nhưng lại giúp làm rõ ý nghĩa, cấu trúc và logic của mã nguồn. Việc sử dụng comment đúng cách không chỉ giúp chương trình dễ đọc, dễ bảo trì mà còn thể hiện tính chuyên nghiệp của lập trình viên.

Trong bài học này, mình sẽ cùng tìm hiểu cách viết comment trong PHP, các loại comment thường dùng, ví dụ minh họa thực tế và những lưu ý quan trọng khi sử dụng.

Khái niệm comment trong PHP

Comment là gì?

Comment (hay còn gọi là chú thích) là những đoạn văn bản được chèn vào mã nguồn nhưng không được thực thi bởi trình thông dịch PHP. Khi chương trình chạy, những dòng comment sẽ bị bỏ qua hoàn toàn, không ảnh hưởng đến kết quả hay hiệu suất của chương trình.

Mục đích của comment

Comment không làm thay đổi logic chương trình nhưng có vai trò rất quan trọng trong việc:

Giải thích đoạn mã: Giúp người khác hoặc chính bạn hiểu rõ từng phần mã viết ra, đặc biệt là những đoạn có logic phức tạp.
Dễ dàng bảo trì và nâng cấp: Khi cần sửa hoặc cập nhật, comment giúp bạn nắm bắt nhanh mục đích ban đầu của đoạn mã.
Tạm thời vô hiệu hóa mã: Khi thử nghiệm hoặc debug, bạn có thể dùng comment để "tắt" một đoạn mã mà không cần xóa nó.
Ghi chú công việc: Ghi lại những việc cần làm (TODO), lỗi cần sửa (FIXME), hoặc ghi chú dành riêng cho nhóm phát triển.

Khi nào nên sử dụng comment

Khi viết một hàm phức tạp, cần mô tả rõ chức năng và cách hoạt động.
Khi đặt tên biến/hàm chưa đủ rõ ràng, nên thêm chú thích đi kèm.
Khi có đoạn mã cần kiểm tra nhưng chưa muốn xóa hẳn.
Khi làm việc nhóm, cần giao tiếp hoặc ghi chú trong mã nguồn.

Ví dụ:

<?php
// Gán giá trị cho biến tên người dùng
$name = "Hoa";

/* 
    Tính tuổi dựa trên năm sinh.
    Giả sử năm hiện tại là 2025
*/
$birthYear = 2000;
$age = 2025 - $birthYear;

echo "Tuổi của bạn là: $age";
?>

Các loại comment trong PHP

Trong PHP, có hai loại comment chính: comment một dòng và comment nhiều dòng. Tùy vào mục đích và độ dài của ghi chú, bạn có thể chọn loại comment phù hợp để sử dụng.

Comment một dòng

Cú pháp:

// Ghi chú ở đây
hoặc # Ghi chú ở đây

Đặc điểm:

Dùng khi bạn muốn chú thích ngắn gọn cho một dòng lệnh.
Comment bắt đầu từ ký hiệu // hoặc # và kết thúc khi xuống dòng.

Ví dụ:

<?php
// Gán tên người dùng
$name = "Hoa";

# Gán tuổi
$age = 25;

echo $name; // In tên ra màn hình
?>

Comment nhiều dòng

Cú pháp:

/* 
    Ghi chú dòng 1
    Ghi chú dòng 2
    ...
*/

Đặc điểm:

Dùng để mô tả nhiều dòng liên tiếp trong mã nguồn.
Thích hợp khi bạn cần ghi chú chi tiết logic xử lý, mô tả hàm, class hoặc chức năng phức tạp.

Ví dụ:

<?php
/*
    Hàm này dùng để tính tổng của hai số.
    Được sử dụng trong các phép tính đơn giản.
    Người viết: Hoa
*/
function sum($a, $b) {
    return $a + $b;
}

echo sum(3, 5);
?>

So sánh nhanh giữa hai loại comment

Loại comment	Ký hiệu	Dùng khi nào
Một dòng	`//` hoặc `#`	Chú thích ngắn, đơn lẻ
Nhiều dòng	`/* ... */`	Mô tả chi tiết, nhiều dòng

Ví dụ minh họa comment trong php

Ví dụ về comment một dòng

Comment một dòng thường được dùng để chú thích nhanh cho một lệnh hoặc biến cụ thể. Có thể dùng // hoặc #.

Ví dụ 1: Dùng `//` để chú thích

<?php
// Khai báo tên người dùng
$name = "Hoa";

// Gán tuổi
$age = 25;

echo $name; // In tên người dùng ra màn hình
?>

Ví dụ 2: Dùng # để chú thích (cũng tương đương)

<?php
# Đây là một comment một dòng dùng dấu thăng
# Gán giá trị cho biến
$country = "Việt Nam";

echo $country; # In tên quốc gia ra màn hình
?>

Ví dụ về comment nhiều dòng

Comment nhiều dòng rất hữu ích khi bạn cần mô tả một đoạn mã phức tạp, giải thích chi tiết cách hoạt động, hoặc viết thông tin nhóm phát triển.

Ví dụ:

<?php
/*
    Đây là một ví dụ về comment nhiều dòng trong PHP.
    Đoạn comment này có thể ghi chú dài dòng hoặc giải thích thuật toán.
    Bạn có thể sử dụng nó để mô tả chức năng của đoạn mã bên dưới.
*/

// Khai báo hai số
$a = 10;
$b = 20;

/*
    Hàm cộng hai số và in ra kết quả.
    Người viết: Hoa
    Ngày: 2025-06-16
*/
function add($x, $y) {
    return $x + $y;
}

// Gọi hàm và in kết quả
echo "Tổng là: " . add($a, $b);
?>

Ứng dụng comment thực tế trong PHP

Comment không chỉ để ghi chú đơn thuần, mà còn là công cụ quan trọng trong việc làm việc nhóm, bảo trì mã, thử nghiệm tính năng, và quản lý tiến độ phát triển phần mềm. Dưới đây là những ứng dụng phổ biến nhất:

Ghi chú chức năng của biến, hàm, class

Giúp người đọc hiểu rõ vai trò, kiểu dữ liệu, và mục đích sử dụng của từng thành phần trong chương trình.

Ví dụ:

<?php
// Biến lưu tên người dùng (kiểu string)
$name = "Hoa";

// Hàm tính diện tích hình tròn
function tinhDienTich($banKinh) {
    // Công thức: pi * r^2
    return 3.14 * $banKinh * $banKinh;
}
?>

Ghi thông tin tác giả, ngày viết, mục đích đoạn mã

Đặc biệt hữu ích khi làm việc theo nhóm hoặc lưu trữ mã lâu dài.

Ví dụ:

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

function kiemTraDangNhap($username, $password) {
    // Logic kiểm tra tài khoản
}
?>

Vô hiệu hóa tạm thời một đoạn mã trong quá trình kiểm thử

Giúp tắt một phần chương trình mà không cần xóa, phục vụ cho việc test hoặc debug.

Ví dụ:

<?php
echo "Chạy phần A<br>";

/*
// Tạm thời tắt phần B để test phần A
echo "Chạy phần B<br>";
echo "Chạy phần C<br>";
*/

echo "Chạy phần D<br>";
?>

Kết quả chạy: chỉ in "Chạy phần A" và "Chạy phần D", vì phần B – C đã bị comment lại.

Ghi TODO, NOTE, hoặc các đánh dấu đặc biệt cho nhóm phát triển

Ghi chú công việc chưa làm (TODO), vấn đề cần xem lại (FIXME), hoặc lưu ý đặc biệt (NOTE). Đây là một phần quan trọng của quy trình phát triển chuyên nghiệp.

Ví dụ:

<?php
// TODO: Cần kiểm tra đầu vào cho hàm này để tránh lỗi
function chia($a, $b) {
    return $a / $b;
}

// NOTE: Cần thêm xác thực token ở đây
// FIXME: Đôi khi biến $b có thể bằng 0, gây lỗi chia cho 0
?>

Lỗi cần tránh khi dùng comment trong PHP

Việc sử dụng comment là tốt, nhưng nếu dùng không đúng cách có thể gây hiểu nhầm, rối mã, thậm chí gây lỗi cú pháp khi chạy chương trình. Dưới đây là một số lỗi phổ biến cần lưu ý:

Quên đóng */ trong comment nhiều dòng

Khi sử dụng comment nhiều dòng /* ... */, nếu quên đóng thẻ */, toàn bộ phần phía sau có thể bị hiểu sai thành comment → dẫn đến lỗi cú pháp hoặc chương trình không chạy đúng.

Ví dụ sai:

<?php
/* Đây là đoạn comment chưa đóng

echo "Xin chào!"; // Dòng này không được thực thi vì nằm trong comment
?>

Cách đúng:

<?php
/* Đây là đoạn comment đã đóng đúng cách */
echo "Xin chào!";
?>

Comment quá nhiều hoặc quá ít

Comment quá nhiều: ghi chú cả những đoạn mã quá rõ ràng → gây rối mắt, làm loãng nội dung chính.
Comment quá ít: không giải thích được logic phức tạp → gây khó khăn khi đọc và bảo trì mã.

Ví dụ: Comment dư thừa

<?php
// Gán giá trị cho biến a
$a = 5; // Gán số 5 cho biến a

// Gán giá trị cho biến b
$b = 10; // Gán số 10 cho biến b

// Tính tổng của a và b
$c = $a + $b; // Cộng a với b và gán vào c

echo $c; // In ra kết quả
?>

Vấn đề: Những đoạn comment như “gán giá trị”, “cộng a với b” là quá rõ ràng, không cần thiết.

Cách hợp lý hơn:

<?php
// Tính tổng số lượng đơn hàng trong ngày
$orderToday = 120;
$orderYesterday = 90;

$totalOrder = $orderToday + $orderYesterday;

echo "Tổng đơn hàng: $totalOrder";
?>

Viết comment không rõ ràng hoặc sai với chức năng thực tế

Comment nên mô tả đúng logic, nếu không sẽ dễ gây hiểu nhầm cho người đọc hoặc lập trình viên khác.

Ví dụ: Comment sai nội dung

<?php
// Hàm này dùng để trừ hai số (Thực tế là cộng)
function tinh($a, $b) {
    return $a + $b;
}
?>

Vấn đề: Comment nói là “trừ” nhưng hàm lại đang thực hiện phép cộng. Điều này gây nhầm lẫn nghiêm trọng.

Cách đúng:

<?php
// Hàm cộng hai số
function tinh($a, $b) {
    return $a + $b;
}
?>

Kết những lỗi thường gặp khi dùng comment

Lỗi thường gặp	Ảnh hưởng
Quên đóng `*/`	Lỗi cú pháp, chương trình không chạy được
Viết quá nhiều comment	Gây rối mắt, loãng nội dung chính
Viết quá ít comment	Gây khó hiểu, khó bảo trì mã
Viết comment sai chức năng	Gây hiểu nhầm, mất thời gian khi sửa mã

Kết bài

Comment là một phần không thể thiếu trong lập trình PHP cũng như bất kỳ ngôn ngữ lập trình nào. Việc sử dụng comment đúng cách không chỉ giúp tăng tính rõ ràng và dễ hiểu cho mã nguồn, mà còn hỗ trợ hiệu quả trong làm việc nhóm, bảo trì hệ thống, và kiểm thử chương trình.

Khi viết comment, lập trình viên nên ghi chú một cách ngắn gọn, chính xác, đúng mục đích và tránh lạm dụng. Đồng thời, cần thường xuyên cập nhật comment theo logic thực tế của chương trình để tránh gây hiểu nhầm.

Với thói quen sử dụng comment khoa học và hợp lý, bạn sẽ viết được những dòng code chuyên nghiệp hơn, dễ đọc hơn và dễ bảo trì hơn – một kỹ năng rất quan trọng trong lập trình hiện đại.