Tìm hiều về chú thích trong Python

Chú thích trong Python đóng vai trò quan trọng, giúp code dễ đọc và dễ hiểu hơn. Vậy, chú thích trong python là gì? Có những loại nào, cách sử dụng ra sao, và tầm quan trọng của chú thích đối với việc xây dựng một chương trình chất lượng? Để khám phá chi tiết hơn về các khái niệm này, mời bạn cùng theo dõi bài viết

Các điểm chính

Khi đọc xong bài viết, bạn sẽ:

• Hiểu rõ mục đích và vai trò của chú thích (comment) trong Python: Bạn sẽ không còn thắc mắc vì sao các lập trình viên lại thích viết chú thích trong code của mình. Chú thích không chỉ là những dòng vô nghĩa, mà là “kim chỉ nam” giúp code dễ đọc và dễ bảo trì hơn.
• Nắm vững các loại chú thích trong Python và cách sử dụng chúng một cách hiệu quả: Bạn sẽ biết cách phân biệt và sử dụng đúng cách chú thích một dòng, chú thích nhiều dòng, và các kiểu chú thích như standalone hay inline.
• Biết cách tận dụng chú thích để tạo tài liệu code (Docstrings) chuyên nghiệp: Docstrings không chỉ giúp bạn hiểu code của mình, mà còn giúp người khác hiểu và sử dụng code của bạn dễ dàng hơn. Bạn sẽ biết cách truy cập và sử dụng Docstrings một cách bài bản.
• Tạo thói quen viết chú thích code ngay từ những dòng code đầu tiên: Đây là kỹ năng quan trọng giúp bạn trở thành một lập trình viên Python chuyên nghiệp và có trách nhiệm.

Chú thích trong Python là gì?

Chú thích trong Python là những giải thích hoặc ghi chú mà lập trình viên thêm vào mã nguồn Python. Mục đích của chú thích là làm cho mã nguồn dễ hiểu hơn đối với con người, còn trình thông dịch Python sẽ bỏ qua các chú thích này. Chú thích làm cho code dễ đọc hơn và giúp lập trình viên dễ dàng hiểu rõ được logic cũng như mục đích của các đoạn code.

Ví dụ về chú thích trong Python

Bạn hãy xem qua đoạn code dưới đây:

# Dòng này là chú thích, sẽ không được in ra màn hình
tien_luong = 5000000 # Đơn vị: VNĐ, chú thích có thể nằm ngay sau câu lệnh.
print("Xin chào, hôm nay trời đẹp!")

Khi thực thi đoạn mã, dòng chữ “Xin chào, hôm nay trời đẹp!” sẽ được in ra màn hình, còn những dòng chú thích sẽ được trình thông dịch bỏ qua và không ảnh hưởng tới luồng chạy của chương trình.

Chú thích một dòng là gì?

Chú thích một dòng trong Python bắt đầu bằng ký hiệu thăng (#) và kéo dài đến hết dòng. Chú thích được sử dụng để cung cấp các giải thích ngắn gọn hoặc ghi chú về mã nguồn. Chú thích có thể được đặt trên một dòng riêng, phía trên đoạn mã mà nó mô tả, hoặc ở cuối một dòng mã (được gọi là chú thích nội dòng) để cung cấp ngữ cảnh hoặc làm rõ cho dòng cụ thể đó.

Mục đích của chú thích:

• Tăng tính dễ hiểu code
• Chú thích không được thực thi khi chạy chương trình, nó là text chỉ có người đọc mới thấy
• Giải thích ý nghĩa của các đoạn code

Chú thích độc lập (Standalone)

Chú thích độc lập là chú thích chiếm toàn bộ một dòng, bắt đầu bằng ký hiệu #. Chú thích này thường được đặt phía trên đoạn code mà nó mô tả. Ví dụ:

# Tính tổng số tiền khách hàng đã mua
def tinh_tong_tien(gia_san_pham, so_luong):
  tong = gia_san_pham * so_luong
  return tong

so_tien = tinh_tong_tien(50000,3) # 50k, 3 sản phẩm
print(so_tien)

Chú thích nội dòng (Inline)

Chú thích nội dòng là chú thích xuất hiện trên cùng một dòng với một đoạn code, đứng sau phần code và cũng bắt đầu bằng #.

Lấy từ ví dụ ở trên ta có chú thích nội dùng như sau

so_tien = tinh_tong_tien(50000,3) # 50k, 3 sản phẩm

Chú thích nhiều dòng là gì?

Trong Python, chú thích nhiều dòng được dùng để cung cấp những giải thích hoặc ghi chú dài, trải dài trên nhiều dòng. Mặc dù Python không có một cú pháp riêng biệt nào dành cho chú thích nhiều dòng, nhưng có hai cách phổ biến để làm điều này: sử dụng liên tiếp các chú thích một dòng, hoặc dùng chuỗi có ba dấu nháy.

Chú thích đơn liên tiếp

Chú thích đơn liên tiếp là việc sử dụng ký tự # ở đầu mỗi dòng. Cách này thường được dùng cho những giải thích dài hơn, hoặc để phân chia các phần code.

Ví dụ: Thay vì ví dụ tính giai thừa (factorial), hãy xem xét ví dụ sau để dễ hình dung.

# Hàm này dùng để kiểm tra một số có phải là số nguyên tố hay không
# Số nguyên tố là số lớn hơn 1 và chỉ chia hết cho 1 và chính nó
# Ví dụ: 2, 3, 5, 7, 11,...

def la_so_nguyen_to(so):
    if so <= 1:
        return False  # Số nhỏ hơn hoặc bằng 1 không phải số nguyên tố

    for i in range(2, int(so**0.5) + 1):
        if so % i == 0:
            return False  # Nếu chia hết cho số nào đó trong khoảng này thì không phải

    return True # Nếu không chia hết số nào thì là số nguyên tố.

kiem_tra_so = 17
if la_so_nguyen_to(kiem_tra_so):
  print(f"{kiem_tra_so} là số nguyên tố")
else:
  print(f"{kiem_tra_so} không là số nguyên tố")

Chuỗi dấu nháy ba (Triple – Quoted Strings)

Chúng ta có thể sử dụng chuỗi có dấu nháy ba ( ''' hoặc """ ) để tạo chú thích nhiều dòng. Về mặt kỹ thuật, chuỗi này là các ký tự chuỗi (string literals), nhưng có thể được dùng như chú thích nếu chuỗi này không được gán cho bất kỳ biến nào hoặc không được dùng trong các biểu thức.

Cách này thường được sử dụng cho các chú thích khối (block comments) hoặc khi cần giải thích chi tiết các phần code. Ví dụ:

"""
Hàm này thực hiện phép chia hai số.
Nếu số chia là 0, hàm sẽ thông báo lỗi.
Nếu số chia khác 0, hàm sẽ trả về kết quả của phép chia.
"""
def phep_chia(so_bi_chia, so_chia):
  if so_chia == 0:
    return "Không thể chia cho 0"
  else:
    return so_bi_chia / so_chia

ket_qua = phep_chia(10, 2)
print(ket_qua)
ket_qua_2= phep_chia(5,0)
print(ket_qua_2)

Sử dụng chú thích để làm tài liệu trong Python

Trong Python, có một loại chú thích đặc biệt, được gọi là docstrings, có công dụng như một tài liệu tích hợp ngay trong code. Docstrings giúp giải thích mục đích và cách sử dụng các module, class (lớp), function (hàm), và method (phương thức). Việc sử dụng docstrings hiệu quả giúp những người khác khi làm việc với code của bạn có thể nhanh chóng hiểu code mà không cần đọc hết toàn bộ chi tiết bên trong.

Docstrings trong Python

Docstrings là một dạng comment (chú thích) đặc biệt, được dùng để tạo tài liệu cho các thành phần như: modules, classes, functions, và methods. Để viết docstrings, bạn sử dụng ba dấu nháy đơn ''' hoặc ba dấu nháy kép """, và đặt docstring này ngay sau phần định nghĩa của thành phần mà docstring đó mô tả (ví dụ, ngay sau dòng định nghĩa hàm).

Điểm đặc biệt của docstrings là ta có thể truy cập bằng code, khiến docstrings trở thành một phần quan trọng của hệ thống tài liệu tích hợp sẵn trong Python. Ví dụ:

def tinh_dien_tich_hinh_chu_nhat(chieu_dai, chieu_rong):
    """
    Hàm này tính diện tích hình chữ nhật.

    Tham số:
    chieu_dai (float): Chiều dài của hình chữ nhật.
    chieu_rong (float): Chiều rộng của hình chữ nhật.

    Trả về:
    float: Diện tích của hình chữ nhật.
    """
    dien_tich = chieu_dai * chieu_rong
    return dien_tich

# Gọi hàm và in kết quả
dien_tich = tinh_dien_tich_hinh_chu_nhat(5, 4)
print(f"Diện tích hình chữ nhật là: {dien_tich}") # Kết quả: 20

Hướng dẫn truy cập Docstrings

Docstrings có thể được truy cập bằng cách sử dụng thuộc tính .__doc__ hoặc hàm help(). Điều này giúp việc xem tài liệu cho bất kỳ module, class, function, hoặc method trở nên dễ dàng, ngay từ dấu nhắc tương tác của Python hoặc ngay trong code.

Ví dụ: Sử dụng thuộc tính .__doc__

def chuc_mung_sinh_nhat(ten):
    """
    Hàm này gửi lời chúc mừng sinh nhật tới người có tên được truyền vào.

    Tham số:
    ten (str): Tên của người được chúc mừng.

    Kết quả trả về:
    Không có (None).
    """

print(chuc_mung_sinh_nhat.__doc__)

Ví dụ: Sử dụng hàm help()

def chuc_mung_sinh_nhat(ten):
    """
    Hàm này gửi lời chúc mừng sinh nhật tới người có tên được truyền vào.

    Tham số:
    ten (str): Tên của người được chúc mừng.

    Kết quả trả về:
    Không có (None).
    """

help(chuc_mung_sinh_nhat)

Lời kết

Vậy là chúng ta đã cùng nhau tìm hiểu chi tiết về chú thích (comment) trong Python, từ khái niệm, các loại chú thích (một dòng, nhiều dòng), cho đến cách sử dụng chúng để tạo tài liệu (docstrings). Hy vọng rằng với những kiến thức này, bạn sẽ viết code Python dễ đọc, dễ hiểu hơn, và đặc biệt là dễ dàng bảo trì và làm việc nhóm hiệu quả hơn.

Mọi người cũng đọc