Python Từ Cơ bản Đến Nâng cao

Bài 2.5. Ghi chú (Comments)

Ghi chú là một tính năng cực kỳ hữu ích trong hầu hết các ngôn ngữ lập trình. Khi các chương trình của bạn trở nên dài hơn và phức tạp hơn, bạn nên thêm các ghi chú để mô tả cách tiếp cận và logic của mã. Ghi chú cho phép bạn viết các giải thích bằng ngôn ngữ tự nhiên trong chương trình của mình.

Các loại ghi chú trong Python

1. Ghi chú một dòng

Trong Python, dấu thăng (#) chỉ ra một ghi chú một dòng. Python sẽ bỏ qua mọi thứ sau dấu # trên dòng đó:

# Đây là một ghi chú một dòng
print("Hello World!")  # Ghi chú có thể đặt sau lệnh

# Tính tổng hai số
a = 5  # Gán giá trị cho a
b = 3  # Gán giá trị cho b
sum = a + b  # Tính tổng

2. Ghi chú nhiều dòng

Python hỗ trợ ghi chú nhiều dòng bằng cách sử dụng ba dấu nháy kép (""") hoặc ba dấu nháy đơn ('''):

"""
Đây là một ghi chú nhiều dòng.
Nó có thể trải dài qua nhiều dòng.
Python sẽ bỏ qua tất cả nội dung trong này.
"""

def calculate_area(radius):
    '''
    Hàm tính diện tích hình tròn
    Tham số:
        radius: bán kính hình tròn
    Trả về:
        Diện tích hình tròn
    '''
    return 3.14 * radius * radius

Các trường hợp nên sử dụng ghi chú

1. Giải thích logic phức tạp:

   # Kiểm tra số nguyên tố bằng thuật toán căn bậc hai
   def is_prime(n):
    if n < 2:
        return False
    # Chỉ cần kiểm tra đến căn bậc hai của n
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True
   

2. Ghi chú TODO:

   # TODO: Thêm xử lý ngoại lệ cho trường hợp đầu vào không hợp lệ
   def divide(a, b):
    return a / b
   

3. Tài liệu API:

   def get_user_info(user_id):
    """
    Lấy thông tin người dùng từ database
    Args:
        user_id (int): ID của người dùng
    Returns:
        dict: Thông tin người dùng dạng dictionary
    Raises:
        ValueError: Nếu user_id không tồn tại
    """
    pass
   

Những điều cần tránh khi viết ghi chú

1. Tránh ghi chú hiển nhiên: ```python # Không nên x = x + 1 # Tăng x lên 1

Nên

x = x + 1 # Đếm số lần lặp trong vòng lặp

2. **Tránh ghi chú thừa:**
```python
# Không nên
###########################
# Khởi tạo biến
###########################
name = "John"

# Nên
name = "John"  # Tên người dùng

Lợi ích của việc sử dụng ghi chú

1. Dễ bảo trì: Giúp người khác (và chính bạn trong tương lai) hiểu mã nhanh hơn
2. Gỡ lỗi: Có thể tạm thời vô hiệu hóa một đoạn mã để kiểm tra lỗi
3. Tài liệu: Tạo tài liệu tự động từ docstrings
4. Cộng tác: Giúp làm việc nhóm hiệu quả hơn

Ví dụ thực tế

class BankAccount:
    def __init__(self, balance=0):
        """
        Khởi tạo tài khoản ngân hàng
        Args:
            balance: Số dư ban đầu (mặc định = 0)
        """
        self.balance = balance

    def deposit(self, amount):
        # Kiểm tra số tiền hợp lệ
        if amount <= 0:
            raise ValueError("Số tiền phải lớn hơn 0")

        # Cập nhật số dư
        self.balance += amount

        # TODO: Thêm ghi log giao dịch
        return self.balance

Nhớ rằng, viết ghi chú là một kỹ năng quan trọng cần được phát triển theo thời gian. Hãy bắt đầu với thói quen tốt này ngay từ đầu để trở thành một lập trình viên chuyên nghiệp.