Chú thích

Vai trò của chú thích

Chú thích là phần văn bản dành cho người đọc mã nguồn. Trình biên dịch hoặc thông dịch thường bỏ qua phần này. Chú thích nên được dùng để giải thích ý định, điều kiện đặc biệt hoặc giả thiết quan trọng, không nên lặp lại điều hiển nhiên trong mã.

Ví dụ cơ bản

# Tinh tong hai so
first_number = 10
second_number = 20
print(first_number + second_number)

program CommentDemo;

var
  firstNumber, secondNumber: Integer;

begin
  { Tinh tong hai so }
  firstNumber := 10;
  secondNumber := 20;
  Writeln(firstNumber + secondNumber);
end.

#include <stdio.h>

int main(void) {
    /* Tinh tong hai so */
    int firstNumber = 10;
    int secondNumber = 20;
    printf("%d\n", firstNumber + secondNumber);
    return 0;
}

#include <iostream>
using namespace std;

int main() {
    // Tinh tong hai so
    int firstNumber = 10;
    int secondNumber = 20;
    cout << firstNumber + secondNumber << endl;
    return 0;
}

// Tinh tong hai so
int firstNumber = 10;
int secondNumber = 20;
Console.WriteLine(firstNumber + secondNumber);

// Tinh tong hai so
const firstNumber = 10;
const secondNumber = 20;
console.log(firstNumber + secondNumber);

// Tinh tong hai so
const firstNumber: number = 10;
const secondNumber: number = 20;
console.log(firstNumber + secondNumber);

package main

import "fmt"

func main() {
    // Tinh tong hai so
    firstNumber := 10
    secondNumber := 20
    fmt.Println(firstNumber + secondNumber)
}

fn main() {
    // Tinh tong hai so
    let first_number = 10;
    let second_number = 20;
    println!("{}", first_number + second_number);
}

Chú thích nhiều dòng

Khi cần giải thích dài hơn một dòng, dùng cú pháp chú thích nhiều dòng (block comment). Thường dùng để mô tả một đoạn mã phức tạp hoặc tạm thời vô hiệu hóa một khối lệnh.

Python không có cú pháp chú thích nhiều dòng chính thức. Cách phổ biến là dùng nhiều dòng #:

# Bước 1: Lấy dữ liệu từ người dùng
# Bước 2: Kiểm tra hợp lệ
# Bước 3: Tính toán và in kết quả

program MultilineComment;

begin
  { Đây là chú thích
    trải qua nhiều dòng
    trong Pascal }
  Writeln('Xin chao');
end.

#include <stdio.h>

int main(void) {
    /* Đây là chú thích
       trải qua nhiều dòng
       trong C */
    printf("Xin chao\n");
    return 0;
}

#include <iostream>
using namespace std;

int main() {
    /* Đây là chú thích
       nhiều dòng trong C++ */
    cout << "Xin chao" << endl;
    return 0;
}

/* Đây là chú thích
   nhiều dòng trong C# */
Console.WriteLine("Xin chao");

/* Đây là chú thích
   nhiều dòng trong JavaScript */
console.log("Xin chao");

/* Đây là chú thích
   nhiều dòng trong TypeScript */
console.log("Xin chao");

package main

import "fmt"

func main() {
    /* Đây là chú thích
       nhiều dòng trong Go */
    fmt.Println("Xin chao")
}

fn main() {
    /* Đây là chú thích
       nhiều dòng trong Rust */
    println!("Xin chao");
}

Khi nào nên viết chú thích

Khi mã thực hiện một quy tắc nghiệp vụ khó thấy ngay.
Khi có giả định đặc biệt về đầu vào, đầu ra hoặc phạm vi giá trị.
Khi cần nhắc lý do chọn một cách làm thay vì cách khác.

Ghi chú theo ngôn ngữ

Thông tin</div>

Python thường dùng # cho chú thích một dòng. Chuỗi tài liệu nhiều dòng tồn tại nhưng mục đích chính là mô tả hàm, lớp hoặc module.

Pascal hỗ trợ nhiều dạng chú thích như { ... } hoặc (* ... *). Trong thực hành hiện đại, nên chọn một dạng thống nhất trong cùng dự án.

C hỗ trợ /* ... */ cho nhiều dòng và // cho một dòng trong chuẩn mới. Dạng nhiều dòng thích hợp khi tạm thời ghi chú một khối mã ngắn.

C++ kế thừa cú pháp chú thích từ C và bổ sung thêm // cho một dòng. Trong mã C++ hiện đại, // thường được ưa dùng hơn vì dễ bật/tắt khi debug.

C# hỗ trợ // cho một dòng, /* ... */ cho nhiều dòng và /// ... cho tài liệu API (XML doc comments). Tài liệu XML được công cụ IDE dùng để hiển thị gợi ý.

JavaScript dùng // cho một dòng và /* ... */ cho nhiều dòng, giống C. Cú pháp JSDoc (/** ... */) được dùng để tạo tài liệu tự động.

TypeScript dùng cú pháp chú thích giống JavaScript. Ngoài ra, TSDoc (/** ... */) được khuyên dùng để mô tả kiểu và hàm trong dự án lớn.

Go dùng // cho một dòng và /* ... */ cho nhiều dòng. Quy ước chính thức là viết // ngay trước khai báo hàm hoặc kiểu để công cụ godoc tự động tạo tài liệu.

Rust dùng // cho một dòng và /* ... */ cho nhiều dòng. Đặc biệt, /// là doc comment cho mục bên dưới và //! là doc comment cho module đang chứa — cả hai đều được rustdoc xử lý.

Lưu ý

Chú thích tốt làm rõ mục đích, còn chú thích yếu chỉ mô tả đúng điều mà mã đã thể hiện. Nếu mã khó hiểu đến mức luôn cần chú thích dài, nên xem lại cách đặt tên hoặc chia nhỏ hàm.

Trong series này: