Sử dụng comment đúng cách trong Python

Python Tutorial | 10/07/2025 by Hoc Python

Việc viết mã không chỉ dừng lại ở chỗ làm cho máy tính hiểu, mà còn phải giúp con người hiểu được. Đó là lúc lời chú thích (comments) trở thành công cụ không thể thiếu. Trong Python, một ngôn ngữ nổi tiếng với sự rõ ràng, việc sử dụng comments đúng cách lại càng quan trọng để duy trì tính dễ đọc và khả năng bảo trì của mã nguồn.Bài này sẽ giới thiệu vai trò của comments, các loại comments trong Python và tầm quan trọng của việc biết khi nào, ở đâu để thêm những dòng giải thích hữu ích, biến code của bạn không chỉ chạy tốt mà còn dễ hiểu, dễ cộng tác.

Comment là gì?

Trong thế giới lập trình, việc viết mã không chỉ dừng lại ở chỗ làm cho máy tính hiểu, mà còn phải giúp con người hiểu được. Đó là lúc lời chú thích (comments) trở thành công cụ không thể thiếu.

Định nghĩa: Những dòng văn bản trong code mà Python sẽ bỏ qua

Comment là những đoạn văn bản mà bạn thêm vào mã nguồn của mình. Khi trình thông dịch Python (công cụ chạy code của bạn) xử lý chương trình, nó sẽ hoàn toàn bỏ qua những dòng này. Điều đó có nghĩa là comment không ảnh hưởng đến cách chương trình hoạt động hay kết quả đầu ra của nó.
Bạn có thể hình dung comment giống như những ghi chú bên lề bạn viết vào một cuốn sách để làm rõ ý nghĩa của đoạn văn bản chính. Những ghi chú đó không phải là một phần của cuốn sách, nhưng chúng giúp bạn (hoặc người khác) hiểu nội dung tốt hơn.

Mục đích chính: Giải thích code cho con người (bản thân bạn và người khác)

Mục đích cốt lõi của comment là giao tiếp với con người, không phải với máy tính.
Khi bạn viết code, có thể bạn hiểu rõ từng dòng lệnh đang làm gì. Nhưng sau vài tuần, vài tháng, hoặc khi một người khác đọc code của bạn, họ có thể không dễ dàng hiểu được lý do tại sao bạn lại viết code như vậy, hoặc logic phức tạp đằng sau một đoạn mã nào đó.

Comment giúp bạn:

Ghi nhớ: Sau này, khi bạn quay lại code của chính mình, các comment sẽ giúp bạn nhớ lại mục đích và cách hoạt động của từng phần.
Hợp tác: Khi làm việc nhóm, comment là cầu nối giúp các thành viên khác hiểu được ý định và thiết kế của bạn, từ đó cộng tác hiệu quả hơn.
Bảo trì: Khi cần sửa lỗi hoặc nâng cấp chương trình, comment sẽ là bản đồ dẫn đường, giúp bạn nhanh chóng xác định được các phần liên quan và thay đổi đúng chỗ.

Tầm quan trọng: Giúp code dễ hiểu, dễ bảo trì, và hợp tác tốt hơn

Một đoạn code "chạy được" không có nghĩa là một đoạn code "tốt". Code tốt là code không chỉ hoạt động đúng mà còn dễ hiểu.
Dễ hiểu: Comment làm cho code trở nên dễ đọc và dễ nắm bắt hơn, đặc biệt với những thuật toán phức tạp hoặc các quyết định thiết kế không rõ ràng.
Dễ bảo trì: Khi có lỗi phát sinh hoặc cần thêm tính năng mới, việc hiểu rõ từng phần code giúp bạn khắc phục và mở rộng chương trình một cách nhanh chóng, giảm thiểu thời gian và công sức.
Hợp tác tốt hơn: Trong các dự án phần mềm, làm việc nhóm là điều tất yếu. Comment hiệu quả giúp các thành viên trong nhóm hiểu rõ vai trò của từng đoạn code, giảm thiểu hiểu lầm và tăng năng suất chung.

Ví dụ cơ bản về vai trò của Comment:

Hãy xem hai đoạn code sau và cảm nhận sự khác biệt:

Ví dụ 1: Code không có Comment (khó hiểu)

x = 10
y = 20
z = x + y
print(z)

Bạn có thể hiểu các phép toán, nhưng không rõ mục đích của x, y, z là gì.

Ví dụ 2: Code có Comment (dễ hiểu hơn nhiều)

# Khai báo biến để lưu trữ số lượng sản phẩm
so_luong_san_pham = 10

# Khai báo biến để lưu trữ giá mỗi sản phẩm
gia_moi_san_pham = 20.5

# Tính tổng giá trị đơn hàng
tong_gia_tri_don_hang = so_luong_san_pham * gia_moi_san_pham

# In tổng giá trị đơn hàng ra màn hình để người dùng biết
print(f"Tổng giá trị đơn hàng là: {tong_gia_tri_don_hang} USD")

Trong ví dụ thứ hai, các comment giúp chúng ta hiểu rõ ràng mục đích của từng biến và từng bước trong chương trình, dù chỉ là một phép tính đơn giản.

Comment giống như việc bạn thêm một lớp "nghĩa" vào code của mình, biến nó từ một chuỗi lệnh máy móc thành một câu chuyện có logic mà con người có thể theo dõi và hiểu được.

Các loại Comment trong Python

Python cung cấp hai cách chính để bạn thêm chú thích vào mã của mình, phục vụ các mục đích khác nhau nhưng đều nhằm tăng cường khả năng đọc hiểu.

Comment một dòng (Single-line Comments)

Ký hiệu: Comment một dòng bắt đầu bằng dấu thăng (#).

Cách dùng:

Ở đầu dòng: Mọi ký tự sau dấu # trên dòng đó sẽ được trình thông dịch Python bỏ qua. Đây là cách phổ biến để thêm các ghi chú tổng quát, giải thích mục đích của một phần code hoặc một nhóm lệnh.
Ở cuối dòng code: Bạn cũng có thể đặt dấu # sau một câu lệnh Python. Trong trường hợp này, phần code trước dấu # sẽ được thực thi bình thường, còn phần sau dấu # trên cùng dòng sẽ là chú thích. Cách này thường dùng để giải thích cụ thể một dòng lệnh phức năng.

Ví dụ cơ bản:

# Đây là một comment một dòng đứng độc lập.
# Nó giải thích mục đích của chương trình này.

ten = "Alice" # Khai báo biến 'ten' để lưu trữ tên người dùng.
tuoi = 30     # Biến 'tuoi' lưu trữ tuổi của người dùng.

print(f"Tên: {ten}, Tuổi: {tuoi}") # In thông tin người dùng ra màn hình.

Comment nhiều dòng (Multi-line Comments / Docstrings)

Ký hiệu: Comment nhiều dòng được tạo bằng cách sử dụng ba dấu nháy kép (""" """) hoặc ba dấu nháy đơn (''' ''') đặt ở đầu và cuối khối văn bản chú thích.

Cách dùng:

Để giải thích một khối code lớn: Khi bạn cần cung cấp một đoạn giải thích dài cho một phần chương trình, một thuật toán phức tạp, hoặc một nhóm các câu lệnh. Mặc dù Python coi đây là các chuỗi ký tự không được gán cho biến (và do đó sẽ bị bỏ qua), nhưng quy ước này được dùng rộng rãi như comment đa dòng.
Đặc biệt quan trọng: Dùng làm Docstrings (chuỗi tài liệu): Đây là trường hợp sử dụng chính và quan trọng nhất của ba dấu nháy trong Python. Khi một chuỗi nhiều dòng được đặt ngay sau định nghĩa của một hàm (function), lớp (class), hoặc module (tệp .py), nó sẽ trở thành Docstring. Docstring cung cấp tài liệu chính thức cho đối tượng đó, và có thể được truy cập bằng các công cụ tự động (như lệnh help() trong Python).

Ví dụ cơ bản:

Sử dụng như comment nhiều dòng thông thường:

"""
Đây là một chương trình đơn giản tính tổng của hai số.
Nó yêu cầu người dùng nhập vào hai số nguyên.
Kết quả sẽ được hiển thị ra màn hình.
"""
so1 = 10
so2 = 20
tong = so1 + so2
print(f"Tổng là: {tong}")

Sử dụng làm Docstring cho hàm:

def tinh_tong(a, b):
    """
    Hàm này nhận vào hai số (a và b) và trả về tổng của chúng.

    Args:
        a (int/float): Số thứ nhất.
        b (int/float): Số thứ hai.

    Returns:
        (int/float): Tổng của a và b.
    """
    return a + b

# Bạn có thể xem docstring của hàm bằng lệnh help() trong trình thông dịch Python
# >>> help(tinh_tong)

Việc lựa chọn loại comment phù hợp tùy thuộc vào độ dài và mục đích của chú thích. Comment một dòng phù hợp cho các ghi chú ngắn hoặc giải thích cụ thể từng dòng lệnh, trong khi comment nhiều dòng và đặc biệt là Docstrings lý tưởng cho các giải thích chi tiết hơn và tài liệu hóa code.

Khi nào và Cách nào để Comment Đúng Cách trong Python

Việc sử dụng comment không phải là thêm vào càng nhiều càng tốt. Mục tiêu là làm cho code dễ hiểu hơn, chứ không phải phức tạp thêm.

Khi nào nên Comment?

Bạn nên thêm comment khi chúng cung cấp giá trị thực sự cho người đọc mã.

Giải thích lý do "tại sao" bạn làm một việc gì đó (logic phức tạp): Mã nguồn cho bạn biết cái gì đang được thực hiện, nhưng comment giải thích tại sao lại làm như vậy. Điều này cực kỳ hữu ích cho các quyết định thiết kế hoặc logic kinh doanh đặc biệt.

Ví dụ:

# Tại sao lại dùng 2.5 thay vì 3?
# Vì theo quy định mới, sản phẩm này có tỷ lệ chiết khấu đặc biệt là 2.5% cho khách hàng thân thiết.
discount_rate = 0.025
final_price = original_price * (1 - discount_rate)

Mô tả các thuật toán hoặc công thức phức tạp: Nếu bạn đang triển khai một thuật toán ít phổ biến hoặc một công thức toán học phức tạp, hãy giải thích các bước hoặc ý nghĩa của nó.

Ví dụ:

# Thuật toán Sàng Eratosthenes để tìm số nguyên tố đến n
# Bắt đầu với một danh sách các số nguyên từ 2 đến n.
# Lặp qua từng số, nếu nó là số nguyên tố, loại bỏ tất cả các bội số của nó.
def find_primes(n):
    """Tìm tất cả các số nguyên tố nhỏ hơn hoặc bằng n."""
    primes = [True] * (n + 1) # Mảng boolean, mặc định tất cả là nguyên tố
    primes[0] = primes[1] = False # 0 và 1 không phải là số nguyên tố

    for p in range(2, int(n**0.5) + 1):
        if primes[p]:
            # Đánh dấu tất cả các bội số của p (bắt đầu từ p*p) là không nguyên tố
            for multiple in range(p*p, n + 1, p):
                primes[multiple] = False

    # Thu thập các số nguyên tố thực sự
    list_of_primes = [p for p, is_prime in enumerate(primes) if is_prime]
    return list_of_primes

Giải thích các biến hoặc hàm có tên không rõ ràng: Mặc dù tốt nhất là đặt tên rõ ràng ngay từ đầu (total_sales thay vì ts), đôi khi bạn có thể phải làm việc với mã cũ hoặc các ràng buộc khác.

Ví dụ (nên tránh nếu có thể, ưu tiên đặt tên rõ ràng hơn):

n = input("Nhập số lượng: ") # n ở đây là số lượng mặt hàng

Tốt hơn:

so_luong_mat_hang = input("Nhập số lượng: ")

Đánh dấu các đoạn code "tạm thời" hoặc cần sửa chữa: Sử dụng các từ khóa chuẩn như TODO, FIXME, BUG, HACK để tạo các ghi chú mà các công cụ phát triển (IDE) có thể nhận diện và giúp bạn theo dõi.

Ví dụ:

# TODO: Cần thêm xử lý lỗi cho trường hợp người dùng nhập chữ thay vì số.
age = int(input("Nhập tuổi của bạn: "))

# FIXME: Giá trị này có vẻ sai khi chạy thực tế, cần kiểm tra lại công thức.
final_calculation = initial_value * (1 + tax_rate) / adjustment_factor

Mô tả chức năng của hàm, lớp hoặc module (dùng Docstrings): Đây là cách chính thức và khuyến nghị để tài liệu hóa các thành phần chính trong code của bạn. Docstrings sẽ hiển thị khi bạn dùng help() trên đối tượng đó.

Ví dụ:

def calculate_area_of_circle(radius):
    """
    Tính diện tích hình tròn dựa trên bán kính.

    Args:
        radius (float): Bán kính của hình tròn.

    Returns:
        float: Diện tích của hình tròn.
    """
    import math
    return math.pi * (radius ** 2)

# Bạn có thể xem docstring bằng cách: help(calculate_area_of_circle)

Khi nào KHÔNG nên Comment?

Không phải lúc nào comment cũng tốt. Comment thừa hoặc lỗi thời có thể gây hại nhiều hơn lợi.

Lặp lại những gì code đã nói rõ (comment thừa): Nếu code đã đủ rõ ràng, đừng comment lại chính nó. Điều này làm cho code trở nên rườm rà và khó đọc hơn.

Ví dụ (Comment thừa):

a = 10 # Gán giá trị 10 cho biến a (Thừa!)
b = 20 # Gán giá trị 20 cho biến b (Thừa!)
c = a + b # Cộng a và b và lưu vào c (Thừa!)

Thay vào đó, hãy viết:

a = 10
b = 20
c = a + b

Mô tả code quá chi tiết, hiển nhiên: Tương tự như trên, đừng giải thích những thứ mà bất kỳ lập trình viên nào cũng có thể hiểu ngay lập tức.

Ví dụ (quá chi tiết):

# Hàm này in ra màn hình chuỗi "Hello, World!"
print("Hello, World!")

Comment những đoạn code không còn dùng nữa (nên xóa đi): Nếu bạn vô hiệu hóa một đoạn code bằng cách comment nó đi, hãy xóa nó hoàn toàn nếu bạn chắc chắn không cần dùng nữa. Code bị comment nhưng không dùng tới sẽ làm tăng kích thước file và gây nhầm lẫn. Sử dụng các hệ thống kiểm soát phiên bản (như Git) để quản lý lịch sử thay đổi của code.

Các mẹo để Comment hiệu quả:

Để viết comment thực sự hữu ích, hãy tuân thủ các nguyên tắc sau:

Ngắn gọn và súc tích: Comment nên ngắn gọn, đi thẳng vào vấn đề. Tránh những đoạn văn dài dòng.
Cập nhật comment khi code thay đổi: Đây là một lỗi phổ biến. Nếu bạn thay đổi logic của code, hãy nhớ cập nhật comment tương ứng. Comment lỗi thời có thể gây hiểu lầm nghiêm trọng.
Sử dụng ngôn ngữ rõ ràng, chính xác: Viết comment bằng ngôn ngữ dễ hiểu, tránh viết tắt khó hiểu hoặc thuật ngữ mơ hồ.

Dùng khoảng trắng để comment dễ đọc hơn: Sử dụng khoảng trắng giữa dấu # và văn bản chú thích để dễ đọc hơn.

Tốt: # Đây là một chú thích.
Không tốt: #Đây là một chú thích.

Viết comment đúng cách là một nghệ thuật và là kỹ năng quan trọng của một lập trình viên giỏi. Nó giúp bạn và đồng nghiệp tiết kiệm rất nhiều thời gian và công sức trong việc phát triển và bảo trì phần mềm.

Ví dụ Thực tế về Comment trong Python

Để củng cố việc hiểu cách sử dụng comment đúng cách, hãy cùng xem một số ví dụ thực tế minh họa cho các trường hợp đã đề cập.

Ví dụ về hàm có Docstring

Docstrings là loại comment đặc biệt được sử dụng để tài liệu hóa các hàm, lớp và module trong Python. Chúng cung cấp mô tả về mục đích của đối tượng, các tham số đầu vào (Args), và giá trị trả về (Returns).

def calculate_discounted_price(original_price, discount_percentage):
    """
    Tính giá sản phẩm sau khi áp dụng chiết khấu.

    Hàm này nhận vào giá gốc của sản phẩm và phần trăm chiết khấu,
    sau đó trả về giá cuối cùng mà khách hàng phải trả.

    Args:
        original_price (float): Giá gốc của sản phẩm.
        discount_percentage (float): Phần trăm chiết khấu (ví dụ: 10 cho 10%).

    Returns:
        float: Giá sản phẩm sau khi đã áp dụng chiết khấu.
               Trả về 0 nếu giá gốc hoặc phần trăm chiết khấu không hợp lệ.
    """
    if original_price < 0 or not (0 <= discount_percentage <= 100):
        # Đây là một comment giải thích lý do trả về 0 cho đầu vào không hợp lệ
        print("Lỗi: Giá gốc hoặc phần trăm chiết khấu không hợp lệ.")
        return 0.0

    discount_amount = original_price * (discount_percentage / 100)
    final_price = original_price - discount_amount
    return final_price

# --- Cách sử dụng Docstring ---
# Khi bạn gọi hàm help() trên hàm này, Docstring sẽ hiển thị:
# >>> help(calculate_discounted_price)
# Output sẽ giống với nội dung của Docstring bên trên.

Trong ví dụ này, chuỗi ba dấu nháy kép ngay sau def calculate_discounted_price(...) chính là Docstring. Nó giải thích rõ ràng chức năng, tham số và giá trị trả về của hàm.

Ví dụ về chú thích logic phức tạp

Khi bạn có một đoạn mã thực hiện một logic kinh doanh đặc biệt, một thuật toán không trực quan, hoặc một giải pháp cho một vấn đề cụ thể, hãy dùng comment để giải thích lý do tại sao bạn lại viết mã như vậy, chứ không phải chỉ là cái gì mã đang làm.

def process_order(items, customer_status):
    total_cost = sum(item['price'] * item['quantity'] for item in items)
    shipping_cost = 5.0 # Phí vận chuyển cơ bản

    # --- Chú thích logic phức tạp ---
    # Logic tính phí vận chuyển đặc biệt:
    # 1. Nếu khách hàng là 'VIP', miễn phí vận chuyển.
    # 2. Nếu tổng giá trị đơn hàng trên 100 USD, giảm 50% phí vận chuyển.
    # 3. Các trường hợp khác áp dụng phí vận chuyển cơ bản.
    # Quy tắc này được đặt ra để khuyến khích khách hàng mua nhiều hơn hoặc trở thành VIP.

    if customer_status == "VIP":
        shipping_cost = 0.0 # Khách VIP được miễn phí vận chuyển
    elif total_cost > 100:
        shipping_cost *= 0.5 # Giảm 50% phí vận chuyển cho đơn hàng lớn
    # else: phí vận chuyển giữ nguyên 5.0

    final_total = total_cost + shipping_cost
    return final_total

Comment ở đây không chỉ nói rằng "đây là logic tính phí vận chuyển" mà còn giải thích ba quy tắc cụ thể và thậm chí cả mục tiêu kinh doanh đằng sau những quy tắc đó. Điều này vô giá khi sau này bạn hoặc người khác cần sửa đổi hoặc hiểu logic này.

Ví dụ về đánh dấu TODO

Các comment với từ khóa đặc biệt như TODO, FIXME, BUG là những dấu hiệu nhắc nhở cho lập trình viên về các công việc cần làm, lỗi cần sửa, hoặc những phần mã tạm thời. Hầu hết các IDE hiện đại đều có thể nhận diện và liệt kê các TODO này, giúp bạn quản lý công việc hiệu quả.

def process_user_input(user_input):
    # TODO: Cần thêm kiểm tra và xử lý đầu vào người dùng không hợp lệ (ví dụ: rỗng, chỉ có khoảng trắng).
    # Hiện tại chỉ cắt bỏ khoảng trắng thừa ở hai đầu.
    cleaned_input = user_input.strip()

    # FIXME: Logic kiểm tra mật khẩu hiện tại còn yếu, cần thêm quy tắc về độ dài và ký tự đặc biệt.
    if len(cleaned_input) < 6:
        print("Mật khẩu quá ngắn.")
        return False

    # BUG: Đôi khi hàm này trả về kết quả sai khi dữ liệu đầu vào chứa ký tự đặc biệt.
    # Cần debug và fix.
    # HACK: Đây là giải pháp tạm thời để vượt qua lỗi hiện tại, không nên dùng lâu dài.
    # Sẽ loại bỏ sau khi có giải pháp chính thức.
    if "abc" in cleaned_input:
        cleaned_input = cleaned_input.replace("abc", "xyz")

    print(f"Đầu vào đã xử lý: {cleaned_input}")
    return True

Các từ khóa như TODO, FIXME, BUG, HACK giúp bạn và đồng đội nhanh chóng nhận biết những phần code cần được chú ý trong tương lai.

Kết bài

Việc nắm vững cú pháp cơ bản của Python là bước khởi đầu quan trọng và thú vị trên con đường lập trình của bạn. Từ sự rõ ràng trong cách sử dụng thụt lề để định nghĩa khối mã, đến tính trực quan của các biến, kiểu dữ liệu và phép toán, Python được thiết kế để dễ đọc và dễ viết. Các cấu trúc điều khiển dòng chảy như if/elif/else và vòng lặp for/while là những công cụ mạnh mẽ giúp bạn điều khiển logic chương trình một cách linh hoạt. Với một cú pháp thân thiện và dễ tiếp cận, Python không chỉ giúp bạn nhanh chóng biến ý tưởng thành code mà còn khuyến khích bạn phát triển thói quen viết mã sạch và dễ bảo trì. Hãy tiếp tục thực hành và khám phá để trở nên thành thạo hơn với ngôn ngữ lập trình đầy tiềm năng này!